From a72831d5c322078260314c305ddd940e4967947d Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 11 Nov 2026 14:17:51 -0300 Subject: design: rings; nothing from after the moment shown From the user. A loop is a ring its blocks sit on, upright, an inner loop a smaller ring touching its parent, a way out leaving along the tangent; layers stay for functions that are trees of branches; the track is withdrawn. A graph shows only what the run has done by the moment shown: counts so far, a block or edge not reached yet drawn quiet, a fold of what is not reached yet that opens when the run arrives (reach, unfold); the rule stands in Forbidden for every block. A pane unrolls from its strip into its whole column and rolls back, so the whole function or the whole stack can be shown for a beat and a far jump is travelled. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- design/README.md | 403 ++++++---- design/mock/22-graph-sort.png | Bin 241323 -> 327316 bytes design/mock/22-graph-sort.svg | 1099 +++++++++++++++------------ design/mock/23-graph-open.png | Bin 152825 -> 0 bytes design/mock/23-graph-open.svg | 229 ------ design/mock/24-graph-strip.png | Bin 64854 -> 76321 bytes design/mock/24-graph-strip.svg | 222 +++--- design/mock/25-blocks-lens-480.png | Bin 36257 -> 40418 bytes design/mock/25-blocks-lens.png | Bin 216534 -> 240101 bytes design/mock/25-blocks-lens.svg | 1469 +++++++++++++++++++----------------- design/mock/42-frame-layouts.png | Bin 360073 -> 362630 bytes design/mock/43-graph-forms.png | Bin 220933 -> 202259 bytes design/mock/43-graph-forms.svg | 467 +++++------- design/mock/frame.py | 60 +- design/mock/graph.py | 1043 ++++++++++--------------- design/motion.md | 96 +-- design/motion/motion.py | 49 +- 17 files changed, 2475 insertions(+), 2662 deletions(-) delete mode 100644 design/mock/23-graph-open.png delete mode 100644 design/mock/23-graph-open.svg diff --git a/design/README.md b/design/README.md index 084b9d6..d50d8c1 100644 --- a/design/README.md +++ b/design/README.md @@ -72,11 +72,11 @@ this table. | | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` | | | [`arc`](#arc) | a pointer to a row of the same panel, drawn | standing, `touched`; a stub | | 3 panel | [`registers`](#registers) | all seventeen: a row each for those the scene moves, the rest three to a row | `quiet` | -| | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | what the state column has left: 12 to 15 slots | +| | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | what the state column has left: 12 to 20 slots | | | [`backtrace`](#backtrace) | the call chain as rows, newest at the bottom | in the `none` split; the view of `calls`; a lens's drawing | | | [`source`](#source) | a window on the file | 14 lines, 8 with a lens | -| | [`disasm`](#disasm) | the instructions round the pc, under the source | 17, 11 or 15 rows; a [`descent`](#descent): a window a call deep, the kernel at the floor; a [`graph`](#graph): the function's blocks as a track | -| | [`lens`](#lenses) | a drawing of some state over the program column, and over the state column the pane it is a view of; with no view, the band across both | `beside`, `subject`, `blocks` | +| | [`disasm`](#disasm) | the instructions round the pc, under the source | 17 or 11 rows; a [`descent`](#descent): a window a call deep, the kernel at the floor; a [`graph`](#graph): the function's blocks, as `rings` or in `layers` | +| | [`lens`](#lenses) | a drawing of some state over the program column, and over the state column the pane it is a view of; with no view, the drawing alone | `beside`, `subject`, `blocks` | | | [`hexdump`](#hexdump) | memory, a `bytes` row a line | typed or by `fields`; `eight` (a stack frame, a word a row); `more` rows; `seen`; `given`; `memory` | | | [`loupe`](#loupe) | the memory round a pointer's target, floating over the context | two at most, in depth | | | [`nodes`](#nodes) [`array`](#array) [`calls`](#calls) [`syscalls`](#syscalls) [`blocks`](#graph) `pages` | the drawings a lens can hold | `nodes` in two rows, a `bin` heading the second | @@ -98,8 +98,8 @@ this table. | | [`open` `close`](#6-verbs) | what a loupe does | | | | [`descend` `cross` `ascend`](#6-verbs) | what a descent does: a call followed down, a system call, a return | | | | [`regroup` `ink` `enlarge` `column` `frame up` `decode` `align`](#6-verbs) | what building a view does (the introduction) | | -| | [`leave` `turn` `spread` `gather`](#6-verbs) | what a graph does: a block left along the track, a loop's turn over its arch, rows into cards and back | | -| | [`dive` `surface` `flash`](#6-verbs) | between the map and the working frame | | +| | [`leave` `turn` `reach` `unfold`](#6-verbs) | what a graph does: a block left along an edge, a loop's turn round its ring, a block or an edge reached the first time, a fold opening | | +| | [`dive` `surface` `flash` `unroll` `roll`](#6-verbs) | between the map and the working frame; a pane and its whole column | | | | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | ## 0. Tokens @@ -683,7 +683,7 @@ the stack gains. `slot`s from rsp, low addresses on top: as many as the state column has under the registers ([the frame](#5-the-frame): twelve as the subject beside eleven rows of registers, fourteen beside a lens, fifteen with -none). `call` spans down its right edge for every frame in view: the +none, twenty with the `blocks` lens). `call` spans down its right edge for every frame in view: the backtrace, drawn on the words that are each frame. rsp and rbp are pins in its lane. Reads the stack words, each frame's extent (the frame-pointer chain, or the unwinder's CFA), and for the roles the saved @@ -749,7 +749,7 @@ the current one when it is longer. Under the source, in every split: a line over its instructions, the thread between them in the margin. Seventeen `insn`s in address order: the pc's, eight above, eight below (`none`, `beside`); eleven (five, the -pc, five) as the subject; fifteen with the `blocks` lens. +pc, five) as the subject and with the `blocks` lens. - Rows above the pc are the function's own instructions where it has them; near its start the window stays full from below. @@ -818,103 +818,131 @@ Its motion is [`descend`, `cross`, `ascend`](#6-verbs). ### graph The disassembly's other form: a function as a graph of its basic blocks, -with what the run did on it. Its form is the **track**: the blocks on one -line in the order they run, each loop closing over the line as an arch -whose blocks sit on its floor, a forward jump that passes blocks dipping -under them. Across in the working frame's `blocks` lens, a block a pill; -down on the map, a block a card that carries its rows. Execution goes -along the line (across in the band, down on the map), and the one thing -that goes back is a loop's arch. +with what the run has done on it **by the moment shown, and nothing +after** (see Forbidden). It is the `blocks` lens's drawing, and on the +map that drawing at the same size. Two forms; a scene names the one it +wants: + +- **`rings`**, the first: each loop a ring its blocks sit on, the mark + going round it the picture of iteration. For a function about loops. +- **`layers`**, the second: the blocks in layers, the path read down, a + fork two columns. For a function that is a tree of branches; with no + loop, `rings` draws exactly this. + +A block in either is a **pill**, 24 high, its ends half circles, upright +(never turned to follow a ring): its offset from the function's start at +12 (`+2f`), the functions it calls after it, faint (`+5f swap`: a call is +not an edge; two named, then `…`), and its visits so far ranged right 12 +from its end (`×11`, `dim`). As long as its words, 116 for `+2f ×11`. + +| State | Drawn | +| --- | --- | +| not reached yet | on the page, a 2-unit `rule` frame, its offset faint, no count. What the code is (where the block is, its edges) is known from the start; what the run will do is not | +| reached | on `raised`, its offset primary, its visits | +| the pc's | framed gold, 3 | +| a fold | blocks not reached yet folded into one (below): dashed 12 on 8, `+5b … · 7` (its first block's offset, how many) | + +| Edge | Drawn | +| --- | --- | +| not taken yet | `rule`, 2 | +| taken | `dim`, 2 | +| the last three taken | the trail's golds, the newest 3 units | +| its head | 8 by 8, on the target's frame, on the edge's last tangent | + +Taken and not taken are told by ink and by form together: a taken edge +ends in its count's block being lit, and the jump's row in the +disassembly under the source says `taken` or `not taken` in words. No +dash means "never": that would need the rest of the run. + +**`rings`.** | Part | Drawn | | --- | --- | -| a block, in the lens | a pill 24 high, its ends half circles, a 2-unit `rule` frame: its offset from the function's start at 12 (`+2f`, primary), its visits ranged right 12 from its end (`×11`, `dim`); as long as its rows at 10 a row, and its text at least. Reached: on `raised`; not yet: on the page, its offset faint, no count. The pc's: framed gold, 3 | -| a block, on the map | a card: a head of 24, raised (its first address in code ink, its lines in Go 18 faint, its visits ranged right), and its `insn` rows: the offset ranged right at 72 in place of the address, the line at 116 on a run's first row, the mnemonic at 128, the operands at 212 as [`insn`](#insn) draws them, a jump's or call's target an `address`; the annotation only in the pc's card (and its rows that ran in the last three steps). As wide as its widest row as drawn, 300 at least. The pc's: framed gold, 2 | -| a long block | on the map, over 16 rows: its first four and last four, a `more` row between (`→ … 9 rows`), unless the pc is in it | -| a call | not an edge. In the lens a hook under the pill where the call's row is (out and back, 10 wide, 6 deep, 2 in `dim`) and the callee's name after it (`swap`, primary); on the map the hook out of the card's right side at the call's row and back in a row down, the name after it | -| the way out | under a block that returns, a stub (14 on the map) and a bar 28 wide | -| a step along the line | an edge to the block next on the line: straight along it, end to end, its head on the target's end (8 by 8 in the lens; on the map 10 down the spine, 40 in from the cards' left). Two blocks next on the line that no edge joins have no line between them | -| a jump past blocks | a forward edge to a block further on: a **dip**, out of the source's foot (16 in from its end), down 10, a quarter circle to its level, along under the blocks it passes, a quarter circle up into the target's foot (16 in from its start), head up. Levels 44 under the line and 16 apart, the one that holds another a level deeper. On the map the same to the right: out of the card's right side at its last row, along to its channel (24 right of the widest card and its hooks, 32 a level), down it, into the target's right side at its head row | -| a loop | its back edge is an **arch**: out of the latch's top (16 in from its end), up 10, a quarter circle to its level, back over the loop's blocks, a quarter circle down into the header's top, head down. Levels 52 over the line and 36 apart, an outer loop's over an inner's. The arch and the floor it stands on are one closed shape: the loop. Its turns so far sit at its centre, under the arch (`×5`, `dim`; mono 20), struck when a turn lands. On the map the same to the left: out of the latch's left side at its last row, up a lane (48 left of the cards, 48 a level), into the header's left side at its head row, the turns in the lobe between the lane and what it holds | -| curves | quarter circles and straight runs only: a dip's or an arch's radius its level less 22 (30 and 66 for the lens's first two arches; 22 and 38 for its dips), 16 on the map. No square corner; nothing crosses a block, and the order and the levels keep edges from crossing where the code nests (two jumps whose spans interleave cross once, as jump arrows do); the map's lanes and channels are the arches and dips turned on their side, not routes found round blocks | -| which is which | the jump's row names its target and the target's head shows the same digits; the fall-through is the other. On the map a conditional's two ways are counted in its jump's row, in words: `taken 5 · not 6` (faint), but in the pc's card, where the row has its own annotation (`taken · reads zf`). No hue says it | -| an indirect jump | `jmp rax`, a table: a stub 24 down and `more`'s dots, faint `targets not known`; each target the run takes becomes an edge as it is taken | -| a tail jump | a jump out of the function: a stub 24 out of the block's end and the function it goes to, its name in primary; no bar | -| a call that does not return | `abort`, `exit`, `__stack_chk_fail`: the call's hook goes out and does not come back, and the block has the way out's bar | -| ink | never taken in the whole recording: `rule`, dashed 12 on 8 (sort's `j > 0` failing). Not taken yet: `rule`, solid (the way out). Taken: `dim`, 2. The last three taken: the trail's golds, the newest 3 units. Taken and not are told by form (dashed, solid) and by the words in the jump's row; the golds say only how recent | - -**Order.** Back edges are found by a walk from the entry in address -order; a loop is a back edge's natural loop (its header and every block -that reaches its latch without passing the header), loops of one header -one loop. The line is the blocks by the longest path from the entry, then -by address; a loop's blocks are kept together from its header, so that -no block outside a loop sits on its floor (clang's sort: `+5d`, the inner -loop's way out, follows the swap's block `+5f`, though it is lower in -memory); the blocks that return come last. For code compiled at -O0 the -line is nearly the disassembly's order, so the pill under the band and -its rows under the source lie the same way. Sort, clang -O0, eleven -blocks: `+0 +12 +1e +24 +2f +56 +5f +5d +97 +99 +a7`, two arches (the -inner loop `+5f` to `+24`, the outer `+99` to `+12`), three dips (`j > 0` -failing past `+2f`, never taken; the inner loop's way out past `+5f`; the -function's way out past everything). - -**In the lens** the track is centred in the band, the line through its -middle with the arches' room over it and the dips' under it; 40 between -pills. Sort is 1622 by 150 in a band of 1792 by 200: whole, nothing to -pan. A function too long for the band is folded, in this order: the -blocks the whole recording never reached, each connected run of them one -dashed pill (`+5b to +b3 · 4 blocks`); a loop the pc is not in and will -not enter again, to one pill (`loop at +5f · 3 blocks · 11 turns`) with -its arch; then the line pans across, by `scroll`'s rules turned on their -side, the pc's pill in its middle third. - -**On the map** the track runs down one column (880), the cards in the -line's order 10 apart on their spine, the lanes on the left, the -channels on the right. Sort's is 1684 high: the column whole -([mock 22](mock/22-graph-sort.png)). A function taller than the column -folds as above, and then continues at the next column's top, `continued`, -as any panel. +| a ring | a circle in the edges' ink, its blocks on it at their centres, clockwise in the order they run from the header, which is at the ring's left (9 o'clock), where the way in arrives from the left. Radius as its pills need, 12 between any two: sort's outer loop 140, its inner 84 | +| an edge to the next block on the ring | the arc between them, cut where each pill's frame is, its head on the arc's tangent | +| the back edge | the arc from the latch to the header, round the ring's foot and up its left: the loop closing | +| an edge inside a loop that passes blocks of it | a fork that rejoins: an arc 30 inside the ring from the one to the other (sort's `j > 0` failing, past `+2f`) | +| a nested loop | its ring outside its parent's, touching it at its header, which is the parent's block at 3 o'clock: the inner header at its own ring's 9 o'clock, so both rings run the same way | +| a loop's way out | along the ring's tangent at the block it leaves from, out of the pill's foot (30 in from the end farther from the ring), straight, then quarter circles of 16 to its target: from a header at 9 o'clock straight down outside the ring; from a block at 3 o'clock down the tangent, under the ring's foot, into its target's end. Never a chord across a ring | +| outside every loop | the blocks lie as `layers` lays them, a ring standing in its layer as one block: the entry to the left of the header, the blocks after the loop under it | +| the turns | at the ring's centre, 30 under it (clear of the line its 9 and 3 o'clock pills lie on): the number in mono 20 and `turns` in Go 18 dim, `5 turns`; nothing before the first | + +Sort, clang -O0, at the 11th compare: two rings (the outer loop `+12 +1e +[+24] +5d +97 +99`, the inner `+24 +2f +56 +5f`), `+0` coming in +from the left, `+a7` under the outer header; 732 by 286, in a pane of 880 +by 344 ([mock 43](mock/43-graph-forms.png), 25). + +**`layers`.** Layers by the longest path from the entry, every back edge +found by a walk from it in address order (both from the code); a block +under its fall-through predecessor, a taken target to its right; edges +out of the foot by the side their target lies on, along the gap, into +the target's top; a back edge up its lane on the left; one that would +cross a block in the channel on the right; every corner a quarter circle +of 12. Layers 12 apart, lanes 10, columns 300. It grows down: past its +pane it pans by `scroll`'s rules, the pc's pill in its middle third. + +**Nothing from after the moment.** The layout is the code's, made once +for the scene (where every block is, what a loop is), and never from the +run: no block placed by how often it will be reached, no fold of what the +whole recording never reaches, no edge drawn as never taken. What changes +is what the run has done: a block is quiet until the run first enters it, +an edge until the run first takes it, and that first time has a verb, +[`reach`](#6-verbs): the edge draws in gold under the mark, and the pill +fills to `raised` as the mark lands, its offset brightening and `×1` +fading in. + +**Too big for its pane.** A function whose pills do not fit folds the +blocks the run has not reached yet: the code beyond each way the run has +not taken, as far as it leads, cut so that no fold leads back into +another, one dashed pill in the place of its first block (libc's `open` +at its `syscall`: `+5b … · 7`, the cancellable call's blocks, and `+be … +· 8`, the way back from the kernel). The layout keeps a fold's room as one +pill; when the run reaches a block in it, it opens +([`unfold`](#6-verbs)): the pills beyond it make room along the layout's +own direction (round the ring, or down the layers), never across it, the +fold's blocks fade in quiet in their places, and the reached one fills. A +fold only opens, never closes again in a scene, so the picture grows the +way the run does and nothing a viewer has learnt moves away. Then, if it +still does not fit, the pane pans. **What the recording knows.** By instruction, every jump and return carries the edge it took, so the path, the counts and the trail are exact. By line or by breakpoint only the blocks the stops are in are known: their visits are counted, the edges are drawn by kind in `rule` with no counts, -and there is no trail. A function past 2 048 instructions has its blocks -without their text (`sqlite3VdbeExec`, 2 510 blocks): it is drawn as the -`blocks` lens draws, its blocks as pills, on the map too. Code with no -bounds (start-up, JIT code) has no graph and stays linear. +and there is no trail. A function past 2 048 instructions (`sqlite3VdbeExec`, +2 510 blocks) is folded from the start to its reached blocks and the folds +between them. Code with no bounds (start-up, JIT code) has no graph and +stays linear. **What a static graph cannot show**, and this one does: how often each -block was entered and each branch went each way, the edges never taken, -the path the run took (the trail), the block the pc is in, and the blocks -the run will reach but has not yet. +block was entered and each branch went each way so far, the path the run +took (the trail), the block the pc is in, and the blocks and edges the +run has not reached yet, quiet until it does. **Where it lives.** -- **The map** draws the disassembly column as the track, cards down one - column, whenever the recording has the function's blocks (the linear 69 - rows otherwise, or when the scene asks). The source is beside it; the - thread is its digits (the gold line number in the pc's card and the - source's plaque): no line crosses the lanes. A descent on the map - stacks tracks: a caller folded to the card that holds its waiting call - and one card either side, the callee's track under it, the kernel's - window under that. -- **The disassembly's minimap** stays the linear column, each block's - first row ticked at its left (2, `rule`), the pc's row gold. A sprint on - the map reads on the map itself as the gold going from card to card. -- **The working frame** keeps the linear rows under the source (rule 6), - each block's first row under a rule with its visits ([disasm](#disasm)). -- **The `blocks` lens**, for a scene about control flow: its drawing the - track, the band across both columns (1792 by 200), and no view: the - pc's block's rows are the disassembly under the source, fifteen rows, - the block's rule and count over its first row, the thread from the - source's line to its run. The pill and the rows are tied by the pc's - gold, by the count's digits, and by lying the same way. No row is drawn - twice. - -The comparison this form was chosen from, with the layered form it -replaced: [mock 43](mock/43-graph-forms.png). Its motion is [`leave`, -`turn`, `spread`, `gather`](#6-verbs). Mocks 22 to 25. +- **The `blocks` lens**, for a scene about control flow: the drawing over + the program column, 880 by 344, and no view: the pc's block's rows are + the disassembly under the source (eleven rows), each block's first row + under a 2-unit `rule` with its visits so far, the thread from the + source's line to its run. The pill and its rows are tied by the pc's + gold and by the count's digits. No row is drawn twice. +- **The map** draws the drawing as it draws any lens's, at its size in the + frame, over the source; the disassembly column stays the linear 69 rows, + each block's first row ruled with its visits ([mock 22](mock/22-graph-sort.png)). + A sprint on the map reads as the gold going round the rings and down + the linear column together. A descent on the map draws the callee's + drawing under its caller's. +- **The disassembly's minimap** is the linear column, each block's first + row ticked at its left (2, `rule`), the pc's row gold. + +The comparison the forms were chosen from, the `track` (a line of +blocks, loops as arches over it) among them: [mock 43](mock/43-graph-forms.png) +shows the two kept. The track is withdrawn: a ring says a loop and a +layer a branch, while a line of blocks said neither, and its arches were +rings flattened to fit a band that the frame no longer asks for. Its +motion is [`leave`, `turn`, `reach`, `unfold`](#6-verbs). Mocks 22, 24, +25, 43. ### lenses @@ -924,10 +952,9 @@ of**, each a panel with its own tag. The gutter between them is the ties', as it is below. Beside the context both are 152 high; as the subject the drawing is 296 and its view 200 ([the frame](#5-the-frame)). A lens with no view of its own (`blocks`, whose rows are the disassembly under the -source) is one panel across the band, 1792 by 200. On the map the drawing -keeps its subject size and the view is its region whole; the `blocks` -lens's drawing is not on the map, whose disassembly column is the same -track with its rows. +source) is its drawing alone over the program column, 880 by 344, and the +state column is the registers' and the stack's from the top. On the map +the drawing keeps its size in the frame and the view is its region whole. | Lens | Drawing | Its view | Mock | | --- | --- | --- | --- | @@ -936,7 +963,7 @@ track with its rows. | `calls` | a call tree under its caller, results on the shoulder | the `backtrace`; each node is also a `call` span on the stack, tied by `project`. Subject only: a tree needs the height | 12; 1 at camera scale | | `backtrace` | the call chain itself, as `call` rows (eleven as subject): how the program came to be here, when that is the story and no one function's calls are | a `hexdump` by `fields` of what the newest call was handed (the struct an argument points at, a buffer), at its stop | 13, 14 | | `syscalls` | the calls so far, as strace writes them, oldest on top; the kernel's own side is the [`descent`](#descent)'s floor | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 14; 16; 3 at camera scale | -| `blocks` | the function's [graph](#graph) as a track: blocks as pills on a line, loops as arches, jumps past blocks as dips; the band across both columns | none: its rows are the disassembly under the source, fifteen | 25; 43 | +| `blocks` | the function's [graph](#graph): `rings` (each loop a ring its blocks sit on) or `layers` (a tree of branches), every count the run's so far | none: its rows are the disassembly under the source, eleven | 25; 43; 22 on the map; 24 | | `pages` | the far view: pages, system calls over time | the mappings, a row each | 8 | | `hexdump` alone | bytes and their text | itself | 5, in its first-pass form | @@ -959,7 +986,7 @@ row reaches `pwrite64`. **What a new lens must provide** to fit the frame: 1. A drawing that fits 856 by 116 (`beside`) and by 260 (`subject`); or, - with no view, 1768 by 164 (the band across). + with no view, 856 by 296 (the `blocks` split's 344). 2. Its view, a pane of rows that fits the state column (five beside, seven as subject; the region whole on the map), and for every element the bytes, slot or register it is drawn from. A lens whose elements @@ -1306,7 +1333,8 @@ controls may cover the foot of, and which the narration says again. what was written, what runs. **The state column** (right): registers over stack: what they act on. **The lens band** (top): what it means, over the program column, and the pane that means it, over the state column; a lens -with no view of its own takes the band across both. The split is the one +with no view of its own is its drawing alone, over the program column, +and the state column is the machine's from the top. The split is the one thing about the layout a scene chooses. The rows below are for a registers panel of 11 rows (sort's: eight @@ -1323,7 +1351,7 @@ shows 6n rows of its column. | `none` | | | 14 lines, 48 to 416; strip 84 | 17, 428 to 868; strip 102 | 11, 48 to 344 | 15, 356 to 748; strip 90 | 4, 760 to 888 | | `beside` | 152, 48 to 200 | 152, 48 to 200: 5 rows; strip 30 | 8 lines, 212 to 436; strip 48 | 17, 448 to 888; strip 102 | 11, 212 to 508 | 14, 520 to 888; strip 84 | in the stack | | `subject` | 296, 48 to 344 | 200, 48 to 248: 7 rows; strip 42 | 8 lines, 356 to 580; strip 48 | 11, 592 to 888; strip 66 | 11, 260 to 556 | 12, 568 to 888; strip 72 | in the stack; the view of `calls` | -| `blocks` | 1792 by 200, 48 to 248, across | none | 8 lines, 260 to 484; strip 48 | 15, 496 to 888; strip 90 | 11, 260 to 556 | 12, 568 to 888; strip 72 | in the stack | +| `blocks` | 344, 48 to 392: `rings` or `layers` | none | 6 lines, 404 to 580; strip 36 | 11, 592 to 888; strip 66 | 11, 48 to 344 | 20, 376 to 888; strip 120 | in the stack | Each panel is a window onto a column of the [map](#the-map-and-the-minimap), and its minimap shows where. @@ -1348,18 +1376,20 @@ panned in a drawing of 296. So: - the source is eight lines with any lens up, and its two rows go to the disassembly: eleven as the subject; - the `blocks` lens has no view: the disassembly stays under the source, - fifteen rows, the band's height is 200, and its drawing, the - [track](#graph), takes the band's whole width, where sort's eleven - blocks and both loops are whole (1622 by 150) with nothing to pan. + eleven rows; its drawing, the [graph](#graph) as `rings`, has the + squarer pane a ring wants over the program column (880 by 344, where + sort's eleven blocks and both loops are whole, 732 by 286, nothing to + pan), and the state column, with no view to hold, is the registers and + a stack of twenty. The band, the caption band (192 with its margin: what a player's controls cover) and the margins are as they were; nothing else gave. | Of the frame | `none` | `beside` | `subject` | `blocks` | | --- | --- | --- | --- | --- | -| context | 69% | 56% | 48% | 52% | -| of it, the registers / the stack | 18% / 24% (were 28% / 14%) | 22% / 28% (were 33% / 17%) | 26% / 28% (were 39% / 15%) | 24% / 26% (were 33% / 13%) | -| lens band (the drawing and its view) | | 13% | 21% | 17% (was 21%, the disassembly its view) | +| context | 69% | 56% | 48% | 54% | +| of it, the registers / the stack | 18% / 24% (were 28% / 14%) | 22% / 28% (were 33% / 17%) | 26% / 28% (were 39% / 15%) | 23% / 40% (were 33% / 13%) | +| lens band (the drawing and its view) | | 13% | 21% | 15% (was 21%, the disassembly its view) | | caption band | 10% | 10% | 10% | 10% | Three layouts were weighed ([mock 42](mock/42-frame-layouts.png)): **A**, @@ -1420,7 +1450,8 @@ each pair in one place: | Where | Was | Now | Why | | --- | --- | --- | --- | -| the `blocks` lens | the disassembly moved over the state column as the band's view, seven rows; the source alone in the program column; the graph in boxes and square lanes over the program column, panning | the disassembly under the source, fifteen rows, the thread in the margin; the graph as a track across the band, whole | a line over its instructions is a pair, and the thread had crossed the frame; the pill and its rows lie the same way, one over the other (mocks 25, 43) | +| the `blocks` lens | the disassembly moved over the state column as the band's view, seven rows; the source alone in the program column; the graph in boxes and square lanes over the program column, panning | the disassembly under the source, eleven rows, the thread in the margin; the graph as rings over it, whole | a line over its instructions is a pair, and the thread had crossed the frame; a loop drawn as a ring is the thing that comes round (mocks 25, 43) | +| the graph's counts | the layout by the whole recording's counts (the hot path straight down), the edges the whole run never takes dashed, the blocks it never reaches folded from the start | the layout from the code; counts so far; what is not reached yet quiet until it is | a picture of a moment holds nothing from after it ([Forbidden](#composition)) | | the registers | seventeen rows, always | the scene's own as rows, the rest three to a row (`quiet`) | the room went to the stack, which carries the frames the scene is about (mocks 40, 41) | | the `syscalls` lens | the kernel's side, on vellum, in the band over the program | the kernel under the `syscall` row, the descent's floor; the band holds the calls so far as strace writes them | the kernel is under the program, and a call's arguments and the kernel's side are now neighbours (mock 14) | | the backtrace: a panel, the calls lens's view, the backtrace lens, the map | newest on top | newest at the bottom, `#0` last | a call goes down: it reads as the tree beside it does, and the backtrace lens's `#0` sits over the source line it is at (12, 13, 19) | @@ -1604,10 +1635,9 @@ lens's drawing, and the loupes open. keeps under it) to the stack's top, folded into `more` after the process's start. Memory: each region the scene touches, up to 32 rows round what was touched, as many as hold something, fieldless rows - folded. The drawing: its subject size, - 880 by 296 (the `blocks` lens has none here: the disassembly column is - its track, with the rows). A loupe: nine rows, beside the memory it - shows. + folded. The drawing: its size in the frame (its subject size, 880 by + 296; the `blocks` lens's 880 by 344, the disassembly column linear + beside it). A loupe: nine rows, beside the memory it shows. - **What it draws.** The rows as the working frame draws them, the marks of the moment (current, struck, read, held, trail), the thread across the gutter between source and disassembly, and an outline round each of the @@ -1647,12 +1677,28 @@ stack's window does not show, its row on the minimap strikes with it and `flash`es so the eye goes there once. That is how nothing is hidden at the working frame's size: it is only small. The minimap is secondary action: every change on it starts 6 f after the primary onset it follows, never on -that frame. Its window glides with the pane's `scroll`. A far jump in the -same column (a `continue` to another loop, a return to a caller in view) -shows there first: the mark's new row lights gold on the strip and the -window glides to it (24 f, `glide`) before the pane fades through (12 out, -12 in); a jump out of the column (another function, another file) fades -the strip through with the pane. +that frame. Its window glides with the pane's `scroll`, and grows or +shrinks with its pane in a `relayout` (the same 48 f). Every change +between a column seen whole and the pane's window on it is a move the eye +follows, never a cut: + +- **A far jump in the same column** (a `continue` to another loop, a + return to a caller in view, the stack's window to another frame), at a + walk: the pane `unroll`s to its column, the window travels to its new + place along it, and the pane `roll`s back in there (96 f in all), the + mark lighting gold at its new row on the way. At a run, where 1.6 s is + too long: the new row lights on the strip, the strip's window glides to + it (24 f), and the pane fades through (12 out, 12 in), the strip having + shown where it went first. +- **A jump out of the column** (another function, another file) is told + on the map, `surface` and `dive`, as a far `continue` is; the strip + fades through with the pane only at a run. +- **"The whole function", "the whole stack"** for a beat, in the frame: + `unroll` and `roll`. +- **`dive` and `surface`** squeeze each column into its strip and back, + the window's outline riding on it (above); **the sprint on the map** + keeps the windows gliding with the pc, so the dive after it starts from + where the eye already is. **What it costs**, measured on the rows the videos draw: 48 units of each pane's width. The source's lines are cut four characters sooner (at 63 in @@ -1673,8 +1719,7 @@ and the registers carry the longest chains. fades the strip through (12 f) as the new window opens. - The [`graph`](#graph) and the `blocks` lens: the lens's drawing is whole and has none; the disassembly under the source keeps the linear - column's strip, each block's first row ticked. The track with its rows - is on the map, which is its own whole. + column's strip, each block's first row ticked. - [`aligned`](#aligned): one strip at the right of its 1792 panel, the listing's whole column, a row of the listing a row of the strip; in `columns` a row's two cells side by side, at the one scale. @@ -1745,15 +1790,17 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves: | `travel` | a value, a card or a pin going from one place to another | `glide`. A value or card: 30 f to 200 units, 36 f to 400, 48 f beyond. A pin goes along its lane, 18 f after the strike that moved it: in a drawing 30 f to the next node or cell, 36 f to one farther; in the stack's lane 24 f to the next row and 2 f a further row, 36 f at most. A pin that comes fades in over 12 f rising 8 units; one that goes fades out over 12 f; a name joining or leaving a pin cross-fades over 12 f. On a `link` the pin rides the line's head instead. 8 f at a run; at a sprint only at a phrase's end | | `open` | a loupe, from a pointer | the pointer's hop framed `read` (6 f); the stem draws from it to the loupe's place, head first, 18 f (30 f over 600 units), `standard`; the loupe rises with the stem's head: it fades in over 12 f from 8 units lower, its shadow growing from nothing to its offset (18 f, `standard`); the target's bright frame lands 6 f after. From a pointer inside a loupe the same, over it, and a third closes the first as it starts. In the slot of the level that read the pointer, or on a beat the caption names | | `close` | a loupe | the deepest first: its stem draws back into its pointer (12 f) and the loupe sinks, fading out over 12 f as it falls 8 units and its shadow shrinks; with the advance of the step it opened in. A loupe the narration keeps across steps closes at each advance and opens again in the idea's slot of the next step that concerns it (36 f, as `open`): the steps between are not drawn under it. Open 120 f without a change is the most | -| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and each pane's column of the map becomes its minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; on the same move the rest of each window's column (the map's panel it is a window on) squeezes into its pane's strip: from its place at half size to the strip's rect, its width and its height each on its logarithm (to 36 of 880, and 4 of 24 a row), so the text thins to strokes as it lands, the window's outline riding on it to become the strip's window; the map's parts no pane takes (the backtrace, the key, the memory round pointers, a loupe's panel) fade where they are, 24 to 72. On the same move the registers' window (the panel whole on the map, every chain) folds as it lands: each quiet register's row glides into its cell, three to a row, its chain past the first hop fading over the move's first 24 f, so that the panel arrives at its height in the frame. 72 to 96: the drawing, whose sizes differ between the two, crossfades from the map's to the frame's within its box; the `blocks` lens's track, which is no window of the map (the map's disassembly column is the track with its rows, and `gather`s into the pane's rows as it travels), fades in across the band. 84 to 96: each squeezed column crossfades into its strip's strokes; the frame's tags, rules and lanes fade in; the veil goes with the last of the map. 96 to 132: still (mock 20) | +| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and each pane's column of the map becomes its minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; on the same move the rest of each window's column (the map's panel it is a window on) squeezes into its pane's strip: from its place at half size to the strip's rect, its width and its height each on its logarithm (to 36 of 880, and 4 of 24 a row), so the text thins to strokes as it lands, the window's outline riding on it to become the strip's window; the map's parts no pane takes (the backtrace, the key, the memory round pointers, a loupe's panel) fade where they are, 24 to 72. On the same move the registers' window (the panel whole on the map, every chain) folds as it lands: each quiet register's row glides into its cell, three to a row, its chain past the first hop fading over the move's first 24 f, so that the panel arrives at its height in the frame. 72 to 96: the drawing, whose sizes may differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: each squeezed column crossfades into its strip's strokes; the frame's tags, rules and lanes fade in; the veil goes with the last of the map. 96 to 132: still (mock 20) | | `surface` | from the working frame to the map | the dive backwards, a little quicker: 0 to 12 the tags, rules and lanes fade out and each strip's strokes become its column's text; 12 to 84, `glide`, each pane shrinks into its window on the map as its strip unfolds into the column round it, the map's other parts fading in where they are; 84 to 96 the veil lifts; then the map is still 36 f before anything plays on it | | `flash` | a pane's minimap, at a mark its window does not show | a ring 8 across in the mark's colour, on the mark's row in the strip, draws out to 14 and is gone, 12 f, with the mark's own strike or read | +| `unroll` | a pane, to its whole column, for a beat, without leaving the frame ("the whole function", "the whole stack") | the strip's column grows out of the strip over the pane and the panes under it (veiled, 18 f), to the stage's height or the column's, a row of the map's 4 units scaling up on the logarithm to as many as fit (sort's 79 rows of text in 840: 10 a row, shapes and inks; a 22-line file at 24, readable), `glide`, 36 f; the window's outline rides from the strip to its place in the column; the pane's own rows are that window, so nothing appears or vanishes: they are the column's rows round the outline. Held while the caption needs it (60 f at least). `roll` is the reverse, 36 f: the column shrinks back into the strip, the outline lands as the strip's window, the panes under it unveil. A far jump in the same column is `unroll`, the window travelling to its new place along the column (24 f, `glide`), and `roll` | | `descend` | a call the narration follows down | 0 to 12 fire on the call row; rsp struck (24); the stack slides and the return address is struck (30 to 60), as for any call; then the caller's window closes round its call row, in two moves and never both at once: 66 to 78 the rows it gives up fade (those after its return row, and from its top as many as the callee needs), then 78 to 96 the rows it keeps glide up to their places (`glide`), where they move at all; 84 to 96 the call row's plaque becomes the ring; 96 to 114 the call lane draws down from the ring, head first, `standard`; 108 to 120 the callee's head fades in rising 8 as the lane reaches it; 114 to 138 its rows, top down, 2 f apart, 12 f each; 138 to 150 the advance: the plaque lands on the callee's first row, and the source line goes `waiting` (6 f) where the callee has none. Through a stub's `jmp`: the stub's other rows fade (12 f), then its `jmp` row, `pass`, glides to its place (18 f, `glide`), the lane runs on to the next head (18 f), the next window comes in the same way. A label that changes with it (the stack span's name, the source's tag) crossfades, 12 f | | `cross` | a `syscall` row, in a descent | 0 to 12 fire; 18 to 36 the registers that carry the call framed as read, 6 f apart, the argument rows under the row with them (`echo`); 48 to 72 the crossing lane draws down, 3 units, vellum; 66 to 78 the kernel's window opens as it lands, the vellum filling down from the lane's head; 78 to 90 its head and the call fade in, 6 f apart; the work (bytes given or filled, motion.md's chart); `returns` struck; then the answer climbs the lane (24 f) and rax is struck as it lands, the clobbered registers 6 f apart after it, the log's new row fading in (secondary); hold 36; the advance: the kernel's window draws back up into the lane (12 f) and the lane into the plaque (12 f) as the plaque moves on | | `ascend` | a `ret` out of a descent's window | 0 to 12 fire; 18 to 24 the return address framed as read on the stack; rsp struck (36); 48 to 72 the window closes, its rows fading bottom up, 2 f apart, 12 f each, its head last; 72 to 84 the lane draws back up into the ring; the caller's window opens in the reverse order of its closing: 84 to 102 the rows it kept glide back down (`glide`), then 102 to 114 the rows it gave up fade in; 114 to 126 the ring becomes a trail bar, the call row's annotation takes the result (6 f), and the plaque lands on the row after the call; the source line from `waiting` to `current` | -| `leave` | a block of a graph, along the track | 0 to 12 fire on its last row (in the disassembly under the source; in the lens its pill's gold frame pulses with it); a conditional's compare row has its chips framed as read (18 to 24): the cause; 24 to 42 the edge it takes draws gold (3 units) from the source's end or foot to the target, head first, `standard`; then the mark travels it: the gold plaque (22, its point the way it goes) leaves the pill along the edge, `glide`, 12 f and 2 f a 100 units, 42 f at most (a step along the line, 40 units, 12 f; the inner loop's way out under the swap, 331, 18 f; on the map the same edges are 10 and 816), the pill cooling to the trail as it goes; it lands on the target (the advance) and 6 f after, the target's count is armed and struck; with the landing the oldest of the three trail edges cools to `dim` (18 f). A fall-through leaves the same way. At a walk, 1.5 s | -| `turn` | a loop's back edge | `leave` over the arch: up out of the latch, back over the loop's blocks, down into the header; the mark keeps its speed (the inner arch, 672 units, 26 f; the outer, 1433, 40 f), and the loop's count at its centre is armed as the mark comes over and struck as it lands. Going round, floor and arch, is the picture of iteration | -| `spread` | the rows into a graph (on the map, or in a `dive` or `surface` between the track's cards and the working frame's rows) | the track's order is the column's but where a loop's blocks are kept together, so the cards open where they stand: 0 to 24 the column parts at each block's first row, the rows below each break gliding down (`glide`), 10 a break and a head's 24, top down 2 f apart; a block whose place on the line is not its place in memory (clang's sort: `+5d` after `+5f`) glides to it on the same 24 f, only over page, never over text; 24 to 36 the cards' frames and heads fade in round their rows; 36 to 60 the edges draw along the line top down, then the lanes and channels, 2 f apart, 12 f each. `gather` is the reverse: edges out (12 f), frames and heads out (12 f), then the rows close up (24 f) | +| `leave` | a block of a graph, along an edge | 0 to 12 fire on its last row (in the disassembly under the source; in the lens its pill's gold frame pulses with it); a conditional's compare row has its chips framed as read (18 to 24): the cause; 24 to 42 the edge it takes draws gold (3 units) from the source pill's frame to the target's, head first, `standard`; then the mark travels it: the gold plaque (22, its point the way it goes) leaves the pill along the edge, round an arc of the ring or along a way out, `glide`, 12 f and 2 f a 100 units, 12 f at least and 42 f at most (sort's steps round a ring, 58 to 72 units, 12 f; its inner loop's way out, 318, 18 f), the pill cooling to the trail as it goes; it lands on the target (the advance) and 6 f after, the target's count is armed and struck; with the landing the oldest of the three trail edges cools to `dim` (18 f). The first time an edge or a block is reached it is also a `reach`. At a walk, 1.5 s | +| `turn` | a loop's back edge | `leave` round the ring's foot from the latch up into the header at 9 o'clock: an arc, the mark at its speed (sort's inner, 58 units, and outer, 50, 12 f each); the count at the ring's centre is armed as the mark leaves the latch and struck as it lands. The mark going round the ring, step by step and then this, is the picture of iteration; at a run the whole loop goes round in one sweep of 8 f a step | +| `reach` | a block or an edge of a graph the run reaches for the first time | the edge draws gold under the mark, from `rule` (the `leave`'s own draw); as the mark lands, the pill fills from the page to `raised` (12 f), its offset brightening from faint to primary, and `×1` fades in (6 f) and is struck. Its counts begin here, never before | +| `unfold` | a fold of blocks not reached yet, when the run reaches one of them | as the mark sets off along the edge into the fold: the pills beyond the fold make room along the layout's own way (round the ring, or down the layers), 24 f, `glide`; the dashed pill splits into its blocks' quiet pills in their places (12 f, 2 f apart in address order); then the mark lands on the one reached (`reach`). A fold only opens | | `regroup` | bytes into a word (the introduction) | walked, on one word ([chart](motion.md#a-word-read), mock 37): the dump goes from sixteen bytes a row to eight (each right half down a row, then left); the other rows are veiled; the word's offsets fade in under its bytes, `low byte` under the first, `high byte` under the last; then the bytes themselves fly, the low byte first, 6 f apart, 36 f each, `glide`: straight up, over on nested arcs a quarter as high as they are long (34 to 120), straight down onto their pair's place in the word's field, 30 apart and ranged right, so that they land reversed, each offset and label going with its byte, and a faint copy fading into each one's place in the dump once it has left; the gaps close to sixteen digits (12 f); the zeros in front are bracketed, `zeros in front`, and fade (12 f). At a run (the other fifteen): each row's word fades in (8 f) as its bytes dim, rows 6 f apart. The word field is eight pairs wide, so a word is always ranged right, its low byte last | | `ink` | a word becoming an address | its digits go from primary to its region's ink (12 f), and the band it points into in `segments` is framed as read inside its box, with the band's row of names (6 f): an echo, no line. The first walked, held 60 f; the rest at a run, 2 f apart, each band framed 12 f | | `enlarge` | a box of `segments`, out of its line on the whole | 0 to 6 the cluster's line on the whole framed bright; 6 to 78, `glide`, the box rides out along the magnification: its left corners travel the two lines from the line to their places, the lines drawn behind them, the box as tall as they are apart and as wide as the ride is far (the bar's 20 to its 180), its bands drawn at its scale all the way (a mapping a 2-unit line until it is taller; the gaps opening); 78 to 90 its page lines fade in and the frame on the line goes; then its names, rows top down, 2 f apart: an edge's leader draws from the box (6 f), then its address fades in (12 f); a band's row fades in (12 f). The clusters in address order, each riding out as the one before lands ([chart](motion.md#the-address-space-enlarged)) | @@ -1765,10 +1812,10 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves: | `advance` | the current marks | last. The thread, the plaques and rip move together: 12 f to an adjacent row, 24 f up to eight rows, `standard`; farther, out and in over 6 f. A taken jump's line draws in the jump lane with it | | `cascade` | a step | `fire` (12); then its effects a level at a time, 18 f apart: CPU (`reg`s, the pc's annotation), memory (`slot`s, `bytes`), the idea (the drawing, by `project`); each armed, then struck; hold 36 f after the last strike and 12 f a further value, 84 at most; `advance`; rest 24 f. A level with nothing on screen to change gives up its slot | | `continue` | a stop far from the last: a breakpoint, not a step. Where the windows' new places are farther than their own heights (another function, another file), it is told on the map: `surface`, the jump there, `dive` | `fire` on the line it leaves from; then the levels as in a `cascade`, but CPU is a wave: every register that changed is struck 2 f after the one above it, in pwndbg's order, the fill in over 6 f, no arm and no pulse (a dozen pulses at once are a flash, and a dozen arms a crowd); memory: the stack's window scrolls or fades to its new place, and the [backtrace](#backtrace)'s frames leave, slide and arrive; the idea; hold 36 f after the last strike; `advance`, the source and disassembly fading through if far; rest. Its marks are only on what was on screen to change | -| `run` | steps that need not be read | over a graph, the mark goes from block to block in 8 f (over an arch, 12), each edge taken flashes to gold and cools in 8 f, counts change in place; at a sprint (on the map) the gold moves only when the block changes, 4 f at most each, the trail's three edges following and the loops' counts ticking at their centres, and the picture settles at the phrase's end. Elsewhere: 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; no strikes, no held corners and no arcs drawing: a value changes in place under an 8 f crossfade, unmarked, and what the run changed is shown settled when it ends (its arcs fade in, 8 f, standing; no corners); no ties but the thread. A caption never names what a run veils. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most. A run longer than a phrase may `surface` and play on the map | +| `run` | steps that need not be read | over a graph, the mark goes from block to block in 8 f, round the rings, each edge taken flashes to gold and cools in 8 f, counts change in place; at a sprint (on the map) the gold moves only when the block changes, 4 f at most each, the trail's three edges following and the loops' counts ticking at their centres, and the picture settles at the phrase's end. Elsewhere: 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; no strikes, no held corners and no arcs drawing: a value changes in place under an 8 f crossfade, unmarked, and what the run changed is shown settled when it ends (its arcs fade in, 8 f, standing; no corners); no ties but the thread. A caption never names what a run veils. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most. A run longer than a phrase may `surface` and play on the map | | `sprint` | steps to be got through | 4 f a step. The drawing grows and the clock sweeps; the source and the band's view are veiled as well; the mark and the pins move only at a phrase's end. Each change of pace ramps at 0.6 of the step before. A sprint plays on the map: `surface` before it, `dive` after it, at the stop it reaches; the windows glide with the pc, the marks flash and fade | | `establish` | a scene's opening | done by 54 f: the panels fade in, 18 f each, 6 f apart (registers, stack, source, disassembly, the band's view, the drawing's panel: 0 to 48); from 30 f the drawing's elements fade in rising 8 units, 12 f each, 2 f apart in address order and all begun by 42 f, each with its row's quiet bracket (an `echo`: no lines). The first caption arrives at 60 f | -| `scroll` | a `source`, `disasm` or `stack` window | whole rows, 24 f, `glide`, before the level it makes room for; marks ride with their rows; the window on the pane's minimap glides with it, the same 24 f (a window fading through moves on its minimap with the fade's out, so the strip shows where it went first). A column's `lead` and the line numbers are the rows' on screen: they change on the scroll's first frame, never before. A window going farther than its own height (eight lines, eleven instructions, twelve slots as the subject) does not scroll, which would only blur: it fades out (12 f) and in at its new place (12 f), and what it brings comes in with no marks | +| `scroll` | a `source`, `disasm` or `stack` window | whole rows, 24 f, `glide`, before the level it makes room for; marks ride with their rows; the window on the pane's minimap glides with it, the same 24 f (a window fading through moves on its minimap with the fade's out, so the strip shows where it went first). A column's `lead` and the line numbers are the rows' on screen: they change on the scroll's first frame, never before. A window going farther than its own height (eight lines, eleven instructions, twelve slots as the subject) does not scroll, which would only blur: at a walk the pane `unroll`s, its window travels along the column, and it `roll`s back in at the new place; at a run it fades out (12 f) and in at its new place (12 f); either way what it brings comes in with no marks | | `relayout` | a change of split | the drawing fades out (12 f); every panel moves to its new box, clipped to the box as it moves (48 f, `glide`); the drawing fades in at its new size (12 f). Nothing else moves under it | | `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`. The panel's tag and whole rows in frame, the rows the visit's steps change in its middle third, never at its edge; a stack visited holds its window still. A visit never veils or clears a panel a drawn tie starts or ends in: it waits until the tie has drawn back, or frames both ends. 120 f at most without a change; back | | `say` | the caption | out 12 f, gap 6 f, in 18 f; the numbers are under [caption](#clock-and-caption) | @@ -1789,7 +1836,7 @@ call down, 3.6 s for a crossing (4.9 s when it moves bytes), 2.5 s back up. **What may contain what.** - The working frame holds the band and two columns; the band is two - panels, one over each column, or one across both (a lens with no view). The map holds the same panels, whole, in + panels, one over each column, or its drawing alone over the program column (a lens with no view). The map holds the same panels, whole, in four columns. A column holds panels. A panel holds a tag and rows, or (a lens) a tag and a drawing, or (a descent) a tag and windows of rows under their heads. A row holds atoms. Nothing nests deeper. @@ -1831,7 +1878,16 @@ call down, 3.6 s for a crossing (4.9 s when it moves bytes), 2.5 s back up. - A mark wider than what changed: bytes struck that kept their value. - A mark on what the viewer could not have seen change: a window that faded to a new place, a panel that came in after its step. -- A text scrolled farther than its window's height: it fades through. +- **A fact from after the moment shown.** Every block draws what the + recording holds up to the moment on screen and nothing later: a count + so far, never the total; a layout from the code or from what has + happened, never from what will (a graph's blocks placed by how often + the run will reach them); no mark for "never" that the rest of the run + decides (an edge never taken, a block never reached); no fold of what + will not be reached. What is not known yet is quiet until it is, and + its arrival is a verb (`reach`, `unfold`). A scene's caption may say + what comes; the picture may not. +- A text scrolled farther than its window's height: it unrolls to its column and rolls back in at the new place, or at a run fades through. - A pin that jumps, two pins for one name, two names in one place. - A space inside a number. A row that wraps. Rows that reorder. - Anything hidden to make room: a row that cannot hold its chain ends in @@ -1850,7 +1906,7 @@ call down, 3.6 s for a crossing (4.9 s when it moves bytes), 2.5 s back up. the block's name; `mock/map.py` draws the working frame from a fresh recording of `targets/list` (9 to 11, 21), the map (19) and the dive (20); `mock/dense.py` holds that recording's data and draws the marks sheet -(15); `mock/graph.py` draws the graphs (22 to 24, and the forms sheet 43) +(15); `mock/graph.py` draws the graphs (22, 24 and the forms sheet 43) from `sort-clang.dis` (sort as the scene builds it, clang -O0), `reverse-O0.dis` and `libc-open.dis` and the paths their runs took; `mock/frame.py` draws the reworked frame (40, 41 from the list recording; @@ -1867,7 +1923,7 @@ python3 -B context.py && for n in 12-calls-subject 13-sqlite-row 14-sqlite-page; resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done; resvg 16-descent.svg 16-descent.png resvg 17-operands.svg 17-operands.png python3 -B heap.py && for n in 18-heap 18-heap-free; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done -python3 -B graph.py && for n in 22-graph-sort 23-graph-open 24-graph-strip 43-graph-forms; do resvg $n.svg $n.png; done +python3 -B graph.py && for n in 22-graph-sort 24-graph-strip 43-graph-forms; do resvg $n.svg $n.png; done python3 -B frame.py && for n in 40-frame-beside 41-frame-subject 25-blocks-lens; do # 42 it composes itself resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done python3 -B pair.py && for n in 26-pair-rest 27-pair-store 28-pair-part 38-pair-ret; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done @@ -1901,11 +1957,10 @@ python3 -B gen.py # 1 to 8, then resvg the same way | [17](mock/17-operands.png) | operands before and after, on real rows of list, hello and libc's `open`; then the row's detail | size words gone; `width` on an immediate store, a byte compare, a sign-extending load; padding faint; a compare's two values and the flags it leaves; conditionals reading them; `lea`'s sum; an indirect jump through `open@got` | | [18](mock/18-heap.png) | the heap scene, five instants of the band: `ztrace dbg` on `mock/heap.c`, glibc 2.44, after each malloc and free (2 a run's end, settled, unmarked) | `nodes` in two rows, a `bin` heading the second (`dummy tcache` before the first free); a free chunk drawn `freed`, its link in its first word; `bytes` read as `size` (`0x20 a m P`) and `protected` (`→ 405050 ^ 405`), notes (`key`, `the old link`); the free list and the program's list as `arc`s; struck bytes, one byte of a pointer struck alone | | [18, the free](mock/18-heap-free.png) | beat 3 in the working frame, mid-step | the register wave a stepped-over call leaves; a `loupe` from the band's view lying over the stack, never the registers, its stem down the gutter's right lane; `rdi` still on the freed chunk; the tcache's two fields, `0x2f8 bytes` | -| [22](mock/22-graph-sort.png) | the map's disassembly as sort's track (clang -O0, eleven blocks), one column beside the source, at the 11th compare (`sort-dbg.txt`) | cards on their spine in the line's order, `+5d` after the loop it leaves; heads with offsets, lines, visits; the pc's card gold with its annotations; the loops as lanes on the left with their turns in the lobes; the jumps past cards down the channels on the right; a conditional's two ways in words in its jump's row (`taken 0 · not 6`); the edge never taken dashed; a call's hook (`swap`); the way out not yet taken; 1684 high in the map's 1688 | -| [23](mock/23-graph-open.png) | libc's `open` at its `syscall` (mock 16's moment 4): 19 blocks, the run's 8, the 11 never reached folded into five cards by what they are | folds of unreached blocks, named, on the line where they lie; blocks the run will reach but has not yet, plain, their ways not counted; twelve-digit heads, offsets in the rows; interleaved jumps crossing once | -| [24](mock/24-graph-strip.png) | reverse's loop in the lens, four instants | `leave`: the condition, the edge lit gold and the mark on it; `turn`: the mark coming round the arch, the count at the loop's centre struck; the way out under the body, landed | -| [25](mock/25-blocks-lens.png) | sort at the 11th compare in the reworked frame with the `blocks` lens | the track across the band, whole: pills with offsets and visits, the pc's gold, two arches with their turns, three dips (one never taken, dashed), the swap's hook, the trail; no view: the disassembly under the source, fifteen rows, each block's rule and visits, the thread to line 12's run; registers `quiet` (eight rows and nine folded); twelve stack slots in sort's, main's and libc's frames; each pane's minimap, the disassembly's ticked at its blocks | -| [43](mock/43-graph-forms.png) | sort's graph four ways at the lens's scale: the present layers, the layers rounded, rings, the track (recommended) | what falls outside the box the frame gives each veiled; what each costs | +| [22](mock/22-graph-sort.png) | the map's first two columns at sort's 11th compare (clang -O0, `sort-dbg.txt`) | the `blocks` lens's rings at their size over the source whole; the disassembly linear, 69 rows (swap, sort, main), each block's first row ruled with its visits so far, `+a7` (not reached yet) with none; the thread across the gutter; the frame's windows outlined on the rows' edges | +| [24](mock/24-graph-strip.png) | reverse's loop as a ring, four instants | `leave`: the condition, the edge lit gold and the mark on the ring's top; `turn`: the mark round the ring's foot, the count at its centre struck (`2 turns`); the way out down the header's tangent to `+48`, reached the first time (`×1`) | +| [25](mock/25-blocks-lens.png) | sort at the 11th compare in the reworked frame with the `blocks` lens | `rings` over the program column, 880 by 344, whole: two rings, the inner touching the outer at its header, upright pills with offsets, calls (`swap`) and visits so far, the pc's gold, the fork inside the inner ring not taken yet, the ways out down the tangents (the function's not taken yet, `+a7` quiet), the turns at the centres, the trail; no view: the disassembly under the source, eleven rows, each block's rule and visits, the thread to line 12's run; registers `quiet` from the state column's top; twenty stack slots in sort's, main's and libc's frames; each pane's minimap | +| [43](mock/43-graph-forms.png) | the graph's two forms at the lens's scale, every count as of the moment shown | `rings` on sort, whole in 880 by 344; `layers` (pills, round corners) on sort, past the pane, veiled; `layers` on libc's `open` at its `syscall`, a tree of branches, its blocks not reached yet folded into two dashed pills (`+5b … · 7`, `+be … · 8`) and `+d0` quiet; why each, and why the track is withdrawn | | [26](mock/26-pair-rest.png) | the `pair` at the loop, i = 15: plain and ASan builds of `overflow.c` | the shared source with each run's mark on its side; two disassemblies aligned by line, ASan's `only here` rows; the line's registers; each frame as bytes (`hexdump` `eight`): plain's `i`, `buf` (`41`s and their `"AAAAAAA"`), the saved rbp and the return address under the span; ASan's fake frame, its header's fields and shadow beside each row, the real stack's way back under a rule; `buf` facing `buf`, the saved rbp facing the redzone (`differs`) | | [27](mock/27-pair-store.png) | one turn of the loop, row by row: plain's eight instructions each facing its counterpart among ASan's seventeen | `only here` bars; the page facing the check; the check's values (`0 : 0 ZF`, `taken`); the partial check and the report's call faint, off the path at 00; under each, its `buf` as bytes, the turn's one byte struck and the reading a letter longer, ASan's shadow framed as read | | [28](mock/28-pair-part.png) | i = 16, the step in which they part | plain's store struck on the saved rbp's first byte, `41` among its stack-ink bytes, its reading `→ 7fffffffed41`; ASan's shadow load framed reading `f3`, its compare and the branch not taken, its redzone still `00`; `differs` on the facing rows | @@ -1975,10 +2030,12 @@ the band. reworked windows outlined, and the dive (20) with the registers folding as they land. The `none` split reworked. A `quiet` cell read; a scene that folds none. -- The track: a pan in the lens; a finished loop folded to one pill; a - third level of arches or dips; an indirect jump and a tail jump on the - line; a descent of tracks on the map; `spread` and `gather` in the new - form, and `leave` and `turn` from a render. +- The graph: `reach` and `unfold` (stills of the folds only, in 43); + `layers` panning; three rings deep; a loop with two ways out, or with + its test at its foot (gcc's rotated loops: the header is still the + ring's 9 o'clock, the latch the block before it round the ring); an + indirect jump and a tail jump; a descent's drawings on the map; `leave` + and `turn` from a render; `unroll` and `roll`. **The data in 22, 24, 25 and 40 to 43** is the recordings' too: sort as `anim/build.zig` builds it for the scene (clang -O0 -g -no-pie @@ -2056,24 +2113,32 @@ is not checked here. The tokens are under [Token changes](#token-changes). free list, a node travelling between them, the free form (dashed, hatched `key`, its link from the first word), and the `bin` box heading the second row. -7. **The graph as a track** ([`graph`](#graph)), in place of the layered - form `graph.zig` draws now (as read on 11 November at 14:15): the - line's order (back edges by a walk from the entry, natural loops, - blocks by the longest path then address, a loop's blocks kept together - from its header, the returning blocks last); arches for back edges and - dips for forward jumps past blocks, each levelled by nesting; every - bend a quarter circle (the radius its level less 22 in the lens, 16 on - the map), no square corner; in the lens a pill a block (offset, visits, - 10 a row long), the call's hook under it, the loops' turns at their - centres; on the map the cards down one column on a spine 40 in, the - lanes 48 apart on the left, the channels 32 apart on the right, a - conditional's two ways in words in its jump's row; the ink with the - never-taken dashed; folds, then a pan along the line; `leave` and - `turn` along the curves at 2 f a 100 units, 42 f at most, the mark a - plaque that points the way it goes; `spread` and `gather` opening the - column at block breaks; the run and the sprint over it. On the map the - disassembly column is one column again, and the panels after it do not - repack. +7. **The graph** ([`graph`](#graph)). What `graph.zig` draws (as read on + 11 November at 14:15: the layered form, laid out by the whole + recording's counts, folding the runs of blocks the whole recording + never reaches, drawing the edges never taken) must change in four + ways. **Nothing from after the moment**: the layout a function of the + code alone (back edges by the walk from the entry in address order, + layers by the longest path, a block under its fall-through + predecessor), never of `countBy`'s `whole` counts; no fold by + `reached` over the whole recording and no never-taken ink: a block or + an edge is quiet until the moment it is first reached (`reach`), and a + fold is of blocks not reached by the moment shown, opening as the run + gets there (`unfold`), its room kept so that only what lies beyond it + moves. **`rings`**, the first form: the natural loops (merged by + header), each a circle of its blocks at their centres clockwise from + the header at 9 o'clock, radius as its upright pills need 12 apart; a + nested loop's ring outside its parent at the parent's 3 o'clock; arcs + for steps round the ring and the back edge; an arc 30 inside for a fork + within a loop; a way out down its block's tangent and quarter circles + of 16; outside the loops, `layers`; the turns at the ring's centre, 30 + under it. **`layers`**, the second, as it is but pills for boxes and + quarter circles of 12 for its corners. **Both**: a block a pill with + its offset, the functions it calls (faint), its visits so far; `leave` + and `turn` along arcs (2 f a 100 units, 12 f at least); the map draws + the drawing as any lens's, and its disassembly column stays linear + with each block's rule and visits (the two-column graph with rows on + the map, and `spread` and `gather`, go). 8. **The pair** ([`pair`](#pair)): the split with a seam, the shared source with a mark per run, two columns of one run each, alignment by line and by variable, `only here` and `differs`, each run's frame as bytes @@ -2113,9 +2178,10 @@ is not checked here. The tokens are under [Token changes](#token-changes). go. 12. **The frame reworked** ([the frame](#5-the-frame)): the disassembly - under the source in every split, `blocks` included (no view: its band - across both columns, 1792 by 200, its drawing the track; the - disassembly fifteen rows); the source eight lines with any lens; the + under the source in every split, `blocks` included (no view: its + drawing over the program column, 880 by 344; the source six lines, the + disassembly eleven; the registers and a stack of twenty from the state + column's top); the source eight lines with any other lens; the disassembly eleven as the subject; the registers `quiet` ([registers](#registers)): the scene's set found once from the recording (the registers any of its moments changes, with rsp, rbp, @@ -2124,8 +2190,13 @@ is not checked here. The tokens are under [Token changes](#token-changes). the panel as tall as its rows and the stack taking the rest (`Split`'s stack and registers from the scene, not fixed per split); the stack's middle half for its scroll; the loupe from the view over the stack's - first six; in the `dive`, the registers folding as they land and the - `blocks` lens's track fading in across the band. + first six; in the `dive`, the registers folding as they land. + +13. **A pane and its column, in motion** ([the minimap](#the-map-and-the-minimap)): + `unroll` and `roll`; a far jump in the same column by `unroll`, the + window travelling, `roll` (in place of a fade through); the strip's + window resizing with its pane in a `relayout`; every strip change 6 f + after the primary onset it follows. **What the recordings must hold**, with the tracer's options: @@ -2179,7 +2250,7 @@ is not checked here. The tokens are under [Token changes](#token-changes). ## Token changes Against `anim/src/theme.zig`: "In theme.zig" is what is in the file, "Is" -what the documents say. The first five rows are this round's, read on 11 +what the documents say. The first seven rows are this round's, read on 11 November at 14:15; the rest were read on 10 November at 23:07, and some may be in since (the pane's `strip` is: the corner minimap's row below is done). The map's, the loupe's and the arc's tokens, the lift's colours, @@ -2187,11 +2258,13 @@ and `metric.bytes` and `metric.slot`'s new columns are in, as asked. | Token | In theme.zig | Is | | --- | --- | --- | -| `layout.split` | `beside` (152, 152, 8 lines, 17, 8 slots, 5); `subject` (296, 200, 10, 9, 6, 7); `blocks`: `subject` with the disassembly 7 rows over the state column and the source 20 | `none` (14 lines, 17; registers, the stack the rest, a backtrace of 4 at the foot); `beside` (152, 152, 8, 17, 5); `subject` (296, 200, 8, 11, 7); `blocks` (a band of 1792 by 200 and no view; 8, 15). In every split the registers are `registers.rows` high and the stack has what the state column has left: `Split` takes the scene's register rows | +| `layout.split` | `beside` (152, 152, 8 lines, 17, 8 slots, 5); `subject` (296, 200, 10, 9, 6, 7); `blocks`: `subject` with the disassembly 7 rows over the state column and the source 20 | `none` (14 lines, 17; registers, the stack the rest, a backtrace of 4 at the foot); `beside` (152, 152, 8, 17, 5); `subject` (296, 200, 8, 11, 7); `blocks` (a drawing of 880 by 344 over the program column and no view; 6, 11; the state column from the top). In every split the registers are `registers.rows` high and the stack has what the state column has left, on the 24 grid, any rest above it: `Split` takes the scene's register rows | | `metric.registers.quiet` | none | three to a row, pitch 285 from 12; the name faint at 0, the value at 48 (60 from the panel's edge); a pointer's chain cut to `more` at once; a 2-unit `rule` over the first quiet row; rip last | -| `metric.graph` | the layered form's: layers 48 apart, blocks 56, lanes 16 from 24, back edge down 14, ports 40, arrivals 48, the channel 32, corners 8; the lens's boxes 24 high, 60 and 10 a row, columns 300 apart, layers 12, lanes 10 | the track's. Map: cards 10 apart on a spine 40 in; lanes 48 apart left of the cards (the first 48 out); channels 24 right of the widest card and its hooks, 32 apart; bends a quarter circle of 16; heads 10 by 10; a conditional's ways in its jump's row at 10 characters past the operands. Lens: pills 24 high, ends round, 10 a row long and the text at least (12 in, 12 from the end), 40 apart, the track centred; arches 52 over the line and 36 apart, dips 44 under and 16 apart, each leaving 16 in from an end, a stub of 10, then a quarter circle of its level less 22; heads 8 by 8; the call's hook 10 wide, 6 deep; the turns at a lobe's centre, 0.4 of the way up it. Kept: a block's head 24 and its rows' columns (72, 116, 128, 212), 300 wide at least, the fold past 16 rows, the way out's stub 14 and bar 28, a call's hook on the map 14 out and a row down, a fold of blocks never reached 520 | -| `time.leave` | chips 0.30, the edge 0.30, the mark 0.20 and 2 f a 100 units, 0.50 at most; count 0.10, trail 0.30, rest 0.70, at a run 0.13 | the same, the mark 0.70 at most (42 f): a lens's outer arch is 1433 units; `turn` the same over its arch, the loop's count armed as the mark comes over and struck as it lands; at a run an arch 0.20 | -| `time.spread` | none | the column parting 0.40 (`glide`, breaks 0.033 apart, top down), frames and heads 0.20, edges 0.20 each, 0.033 apart; `gather` the reverse, the rows closing 0.40 | +| `metric.graph` | the layered form's: layers 48 apart, blocks 56, lanes 16 from 24, back edge down 14, ports 40, arrivals 48, the channel 32, corners 8; the lens's boxes 24 high, 60 and 10 a row, columns 300 apart, layers 12, lanes 10 | a block a pill 24 high, ends round: offset at 12, calls after it faint, visits ranged 12 from the end; 12 apart at least. `rings`: header at 9 o'clock, clockwise; radius as its pills need (sort: 140 and 84); a nested ring outside its parent at the parent's 3 o'clock; a fork inside 30 in; a way out from 30 in from the pill's far end, bends of 16; the turns 30 under the centre (mono 20 and Go 18 `turns`). `layers`: layers 12, lanes 10, columns 300, every corner a quarter circle of 12. Heads 8 by 8. A fold dashed 12 on 8. The pane: 880 by 344. Gone: the boxes with rows on the map, their lanes and channels | +| `time.leave` | chips 0.30, the edge 0.30, the mark 0.20 and 2 f a 100 units, 0.50 at most; count 0.10, trail 0.30, rest 0.70, at a run 0.13 | the same along arcs (sort's steps round a ring are 58 to 72 units: 12 f; its inner way out 318: 18 f); `turn` the same round the ring's foot, the count at its centre armed as the mark leaves the latch and struck as it lands | +| `time.reach` | none | the edge drawn gold under the mark (the `leave`'s own); the pill from the page to `raised` 0.20 as the mark lands, its offset brightening, `×1` fading in 0.10 and struck | +| `time.unfold` | none | the pills beyond make room 0.40 (`glide`, round the ring or down the layers), the fold's blocks fade in 0.20, quiet, 0.033 apart, then the reached one's `reach` | +| `time.unroll` | none | `unroll` 0.60 (`glide`), held 1.00 at least, `roll` 0.60; a far jump: `unroll`, the window's travel 0.40, `roll` | | `time.dive` | none | `bright` 0.10, `veil` 0.30, `move` 1.20 (`glide`, 0.10 between panels), `fade` 0.20 at its end, `still` 0.60; `surface` the same, the move first | | `time.flash` | none | 0.20: a ring from 8 to 14 | | `time.caption_max`, `first_step` | none | 12.00; 4.00, 5.00 when a scene opens on the map | diff --git a/design/mock/22-graph-sort.png b/design/mock/22-graph-sort.png index d536ca4..30ba6e0 100644 Binary files a/design/mock/22-graph-sort.png and b/design/mock/22-graph-sort.png differ diff --git a/design/mock/22-graph-sort.svg b/design/mock/22-graph-sort.svg index b30ffe4..0c2d5e4 100644 --- a/design/mock/22-graph-sort.svg +++ b/design/mock/22-graph-sort.svg @@ -1,486 +1,621 @@ - + - + +the map: sort's rings over the source, the disassembly linear beside them, at the 11th compare - - -sort.c -lines 1 to 22 of 22 -1 -int -a -[ -8 -] -= -{ -4 -, -9 -, -17 -, -31 -, -12 -, -26 -, -5 -, -20 -} -; -2 -3 -void -swap -( -int -* -x -, -int -* -y -) -{ -4 -int -t -= -* -x -; -5 -* -x -= -* -y -; -6 -* -y -= -t -; -7 -} -8 -9 -void -sort -( -int -n -) -{ -10 -for -( -int -i -= -1 -; -i -< -n -; -i -+ -+ -) -{ -11 -int -j -= -i -; - - -12 -while -( -j -> -0 -& -& -a -[ -j -- -1 -] -> -a -[ -j -] -) -{ - -13 -swap -( -& -a -[ -j -- -1 -] -, -& -a -[ -j -] -) -; - -14 -j -- -- -; -15 -} -16 -} -17 -} -18 -19 -int -main -( -void -) -{ -20 -sort -( -8 -) -; -21 -return -0 -; -22 -} -the map: sort's disassembly as its track, in the second column (1024 to 1904), at the 11th compare + + +the blocks of sort +its blocks · the visits so far · the path · the loops' turns + + + + + + + + + + + + + + + + + + + + + + + + + + +5 + turns +5 + turns + ++12 +×6 + ++1e +×6 + ++24 +×11 + ++5d +×5 + ++97 +×5 + ++99 +×5 + ++2f +×11 + ++56 +×11 + ++5f +swap +×5 + ++0 +×1 + ++a7 + + + +sort.c +lines 1 to 22 of 22 +1 +int +a +[ +8 +] += +{ +4 +, +9 +, +17 +, +31 +, +12 +, +26 +, +5 +, +20 +} +; +2 +3 +void +swap +( +int +* +x +, +int +* +y +) +{ +4 +int +t += +* +x +; +5 +* +x += +* +y +; +6 +* +y += +t +; +7 +} +8 +9 +void +sort +( +int +n +) +{ +10 +for +( +int +i += +1 +; +i +< +n +; +i ++ ++ +) +{ +11 +int +j += +i +; + + +12 +while +( +j +> +0 +& +& +a +[ +j +- +1 +] +> +a +[ +j +] +) +{ + +13 +swap +( +& +a +[ +j +- +1 +] +, +& +a +[ +j +] +) +; + +14 +j +- +- +; +15 +} +16 +} +17 +} +18 +19 +int +main +( +void +) +{ +20 +sort +( +8 +) +; +21 +return +0 +; +22 +} - - -disassembly · sort -its blocks · visits · the edges taken · the loops' turns - - - - - - - - - - - - - - - - - - - - - - - - - - -×5 -×5 - - - -401150 -lines 9 to 10 -×1 -+0 -9 -push -rbp -+1 -mov -rbp, rsp -+4 -sub -rsp, 0x10 -+8 -mov -[rbp - 4], edi -+b -10 -mov -[rbp - 8] - - - - -, 1 - - - -401162 -line 10 -×6 -+12 -10 -mov -eax, [rbp - 8] -+15 -cmp -eax, [rbp - 4] -+18 -jge -4011f7 -taken 0 · not 6 - - - -40116e -line 11 -×6 -+1e -11 -mov -eax, [rbp - 8] -+21 -mov -[rbp - 0xc], eax - - - -401174 -line 12 -×11 -+24 -12 -xor -eax, eax -+26 -cmp -[rbp - 0xc] - - - - -, 0 -+2a -mov -[rbp - 0xd], al -+2d -jle -4011a6 -taken 0 · not 11 - - - -40117f -line 12 -×11 -+2f -12 -mov -eax, [rbp - 0xc] -+32 -sub -eax, 1 -+35 -movsxd -rcx, eax -+38 -lea -rax, [rip + 0x2e81] -+3f -mov -eax, [rax + rcx*4] -+42 -movsxd -rdx, [rbp - 0xc] - - - - - -+46 -lea -rcx, [rip + 0x2e73] -+4d -cmp -eax, [rcx + rdx*4] -+50 -setg -al -+53 -mov -[rbp - 0xd], al - - - -4011a6 -line 12 -×11 - -+56 -12 -mov -al, [rbp - 0xd] -7fffffffecd3 -◂ -1 - -+59 -test -al, 1 -1 - : -1 - -zf - - - -+5b -jne -4011af -taken - · reads zf - - - -4011af -lines 12 to 14 -×5 -+5f -13 -mov -eax, [rbp - 0xc] -+62 -sub -eax, 1 -+65 -cdqe - -+67 -lea -rdi, [rip + 0x2e52] -+6e -shl -rax, 2 -+72 -add -rdi, rax -+75 -movsxd -rax, [rbp - 0xc] - - - - - -+79 -lea -rsi, [rip + 0x2e40] -+80 -shl -rax, 2 -+84 -add -rsi, rax -+87 -call -401120 - - -swap -+8c -14 -mov -eax, [rbp - 0xc] -+8f -add -eax, 0xffffffff -+92 -mov -[rbp - 0xc], eax -+95 -12 -jmp -401174 - - - -4011ad -line 12 -×5 -+5d -12 -jmp -4011e7 - - - -4011e7 -line 16 -×5 -+97 -16 -jmp -4011e9 - - - -4011e9 -line 10 -×5 -+99 -10 -mov -eax, [rbp - 8] -+9c -add -eax, 1 -+9f -mov -[rbp - 8], eax -+a2 -jmp -401162 - - - -4011f7 -line 17 -+a7 -17 -add -rsp, 0x10 -+ab -pop -rbp -+ac -ret - - - - -the map's stage ends at 1784 + + +disassembly +sort + +401 +13b +mov +rax, [rbp - 8] +swap +401 +13f +mov +[rax], ecx +401 +141 +mov +ecx, [rbp - 0x14] +401 +144 +mov +rax, [rbp - 0x10] +401 +148 +mov +[rax], ecx +401 +14a +pop +rbp +401 +14b +ret + +401 +14c +nop +[rax] +401 +150 +9 +push +rbp +401 +151 +mov +rbp, rsp +401 +154 +sub +rsp, 0x10 +401 +158 +mov +[rbp - 4], edi +401 +15b +10 +mov +[rbp - 8] + + + + +, 1 +401 +162 +mov +eax, [rbp - 8] +401 +165 +cmp +eax, [rbp - 4] +401 +168 +jge +4011f7 +401 +16e +11 +mov +eax, [rbp - 8] +401 +171 +mov +[rbp - 0xc], eax +401 +174 +12 +xor +eax, eax +401 +176 +cmp +[rbp - 0xc] + + + + +, 0 +401 +17a +mov +[rbp - 0xd], al +401 +17d +jle +4011a6 +401 +17f +mov +eax, [rbp - 0xc] +401 +182 +sub +eax, 1 +401 +185 +movsxd +rcx, eax +401 +188 +lea +rax, [rip + 0x2e81] +401 +18f +mov +eax, [rax + rcx*4] +401 +192 +movsxd +rdx, [rbp - 0xc] + + + + + +401 +196 +lea +rcx, [rip + 0x2e73] +401 +19d +cmp +eax, [rcx + rdx*4] +401 +1a0 +setg +al + +401 +1a3 +mov +[rbp - 0xd], al +7fffffffecd3 +◂ +1 + +401 +1a6 +mov +al, [rbp - 0xd] +7fffffffecd3 +◂ +1 + +401 +1a9 +test +al, 1 +1 + : +1 + +zf + + + +401 +1ab +jne +4011af +taken + · reads zf +401 +1ad +jmp +4011e7 +401 +1af +13 +mov +eax, [rbp - 0xc] +401 +1b2 +sub +eax, 1 +401 +1b5 +cdqe + +401 +1b7 +lea +rdi, [rip + 0x2e52] +401 +1be +shl +rax, 2 +401 +1c2 +add +rdi, rax +401 +1c5 +movsxd +rax, [rbp - 0xc] + + + + + +401 +1c9 +lea +rsi, [rip + 0x2e40] +401 +1d0 +shl +rax, 2 +401 +1d4 +add +rsi, rax +401 +1d7 +call +401120 +swap +401 +1dc +14 +mov +eax, [rbp - 0xc] +401 +1df +add +eax, 0xffffffff +401 +1e2 +mov +[rbp - 0xc], eax +401 +1e5 +12 +jmp +401174 +401 +1e7 +16 +jmp +4011e9 +401 +1e9 +10 +mov +eax, [rbp - 8] +401 +1ec +add +eax, 1 +401 +1ef +mov +[rbp - 8], eax +401 +1f2 +jmp +401162 +401 +1f7 +17 +add +rsp, 0x10 +401 +1fb +pop +rbp +401 +1fc +ret + +401 +1fd +nop +[rax] + +401 +200 +push +rbp +main +401 +201 +mov +rbp, rsp +401 +204 +sub +rsp, 0x10 +401 +208 +mov +[rbp - 4] + + + + +, 0 +401 +20f +mov +edi, 8 +401 +214 +call +401150 +sort +401 +219 +xor +eax, eax +401 +21b +add +rsp, 0x10 +401 +21f +pop +rbp + +×1 + +×6 + +×6 + +×11 + +×11 + +×11 + +×5 + +×5 + +×5 + +×5 + + + + + + + + + + + + + + +the map's stage ends at 1784; the other columns (memory, the registers whole, the stack) as in 19 diff --git a/design/mock/23-graph-open.png b/design/mock/23-graph-open.png deleted file mode 100644 index 1c3e8df..0000000 Binary files a/design/mock/23-graph-open.png and /dev/null differ diff --git a/design/mock/23-graph-open.svg b/design/mock/23-graph-open.svg deleted file mode 100644 index 0d7e9aa..0000000 --- a/design/mock/23-graph-open.svg +++ /dev/null @@ -1,229 +0,0 @@ - - - -the map: libc's open as its track · 19 blocks, the run reached 8; the 11 never reached folded - - - -disassembly · open · libc.so.6 -no source · 19 blocks · folded: 11 never reached - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -7ffff7d10ec0 -×1 -+0 -endbr64 - -+4 -push -rbp -+5 -mov -rbp, rsp -+8 -sub -rsp, 0x70 -+c -mov -[rbp - 0x30], rdx -+10 -mov -rax, fs:0x28 -+19 -mov -[rbp - 0x48], rax -+1d -xor -eax, eax -+1f -test -sil, 0x40 -+23 -jne -7ffff7d10f90 -taken 0 · not 1 - - - -7ffff7d10ee9 -×1 -+29 -mov -eax, esi -+2b -xor -r10d, r10d -+2e -not -eax -+30 -test -eax, 0x410000 -+35 -je -7ffff7d10f90 -taken 0 · not 1 - - -+d0 to +eb -never reached -the O_CREAT path: the mode from the varargs - - - -7ffff7d10efb -×1 -+3b -mov -r11, fs:0x10 -+44 -movsxd -rdx, esi -+47 -mov -eax, [r11 + 0x308] -+4e -cmp -[rip + 0x11018b] - -, 0 -+55 -jne -7ffff7d10fb0 -taken 1 · not 0 - - -+5b to +b3 -4 blocks never reached -multi-threaded: a cancellable call - - - -7ffff7d10fb0 -×1 -+f0 -mov -rsi, rdi -+f3 -xor -r9d, r9d - -+f6 -xor -r8d, r8d - -+f9 -mov -rdi, 0xffffffffffffff9c - -+100 -mov -eax, 0x101 - - - -+105 -syscall - -openat - nr 257 -+107 -mov -rdx, rax - - -+136 to +149 -2 blocks never reached -cancelled - - - -7ffff7d10fca -+10a -cmp -rax, 0xfffffffffffff000 -+110 -ja -7ffff7d10fe8 - - - -7ffff7d10fd2 -+112 -mov -eax, edx - - -+128 to +cd -3 blocks never reached -an error: errno set, -1 returned - - - -7ffff7d10fd4 -+114 -mov -rdx, [rbp - 0x48] -+118 -sub -rdx, fs:0x28 -+121 -jne -7ffff7d10fec - - -+12c to +130 -2 blocks never reached -the canary broken - - - -7ffff7d10fe3 -+123 -leave - -+124 -ret - - - - diff --git a/design/mock/24-graph-strip.png b/design/mock/24-graph-strip.png index 2c1bf80..ab615cd 100644 Binary files a/design/mock/24-graph-strip.png and b/design/mock/24-graph-strip.png differ diff --git a/design/mock/24-graph-strip.svg b/design/mock/24-graph-strip.svg index fda1525..4e9da35 100644 --- a/design/mock/24-graph-strip.svg +++ b/design/mock/24-graph-strip.svg @@ -1,122 +1,126 @@ - + - + 1 the condition the pc on jne in the test's block, the second time; its two ways out - + the blocks of reverse -its blocks · the visits · the path · the loops' turns - - - - - - - - -×1 - -+0 -×1 - -+41 -×2 - -+19 -×1 - -+48 +its blocks · the visits so far · the path · the loops' turns + + + + + + + + +1 + turn + ++41 +×2 + ++19 +×1 + ++0 +×1 + ++48 2 the edge taken -taken: along the line to the body, the mark on the edge, landing +taken: round the top of the ring to the body, the mark on it - + the blocks of reverse -its blocks · the visits · the path · the loops' turns - - - - - - - - -×1 - -+0 -×1 - -+41 -×2 - -+19 -×1 - -+48 - - -3 -the loop's turn -back over the arch to the test, the mark coming round; the count struck as it lands - - - -the blocks of reverse -its blocks · the visits · the path · the loops' turns - - - - - - - - - -×2 - -+0 -×1 - -+41 -×2 - -+19 -×2 - -+48 - - -4 -the way out -not taken, the fourth time: under the body to the exit, landed - - - -the blocks of reverse -its blocks · the visits · the path · the loops' turns - - - - - - - - -×3 - -+0 -×1 - -+41 -×4 - -+19 -×3 - -+48 -×1 +its blocks · the visits so far · the path · the loops' turns + + + + + + + + +1 + turn + ++41 +×2 + ++19 +×1 + ++0 +×1 + ++48 + + +3 +the loop's turn +back round the foot of the ring to the test; the count at its centre struck as it lands + + + +the blocks of reverse +its blocks · the visits so far · the path · the loops' turns + + + + + + + + + +2 + turns + ++41 +×2 + ++19 +×2 + ++0 +×1 + ++48 + + +4 +the way out +not taken, the fourth time: down the tangent, out of the ring, landed + + + +the blocks of reverse +its blocks · the visits so far · the path · the loops' turns + + + + + + + + +3 + turns + ++41 +×4 + ++19 +×3 + ++0 +×1 + ++48 +×1 diff --git a/design/mock/25-blocks-lens-480.png b/design/mock/25-blocks-lens-480.png index af3d2b6..afb981d 100644 Binary files a/design/mock/25-blocks-lens-480.png and b/design/mock/25-blocks-lens-480.png differ diff --git a/design/mock/25-blocks-lens.png b/design/mock/25-blocks-lens.png index 468aee9..c7bea19 100644 Binary files a/design/mock/25-blocks-lens.png and b/design/mock/25-blocks-lens.png differ diff --git a/design/mock/25-blocks-lens.svg b/design/mock/25-blocks-lens.svg index 5041b62..b1f7031 100644 --- a/design/mock/25-blocks-lens.svg +++ b/design/mock/25-blocks-lens.svg @@ -1,744 +1,874 @@ - - + + the blocks of sort -its blocks · the visits · the path · the loops' turns - - - - - - - - - - - - - - - - - - - - - - - - - - -×5 -×5 - -+0 -×1 - -+12 -×6 - -+1e -×6 - -+24 -×11 - -+2f -×11 - -+56 -×11 - -+5f -×5 - -swap - -+5d -×5 - -+97 -×5 - -+99 -×5 - -+a7 - - - -sort.c -lines 8 to 15 of 22 -8 -9 -void -sort -( -int -n -) -{ -10 -for -( -int -i -= -1 -; -i -< -n -; -i -+ -+ -) -{ -11 -int -j -= -i -; - - -12 -while -( -j -> -0 -& -& -a -[ -j -- -1 -] -> -a -[ -j -] -) -{ - -13 -swap -( -& -a -[ -j -- -1 -] -, -& -a -[ -j -] -) -; - -14 -j -- -- -; -15 -} - - - -disassembly -sort -4011 -92 -12 -movsxd -rdx, [rbp - 0xc] - - - - - -4011 -96 -lea -rcx, [rip + 0x2e73] -4011 -9d -cmp -eax, [rcx + rdx*4] -4011 -a0 -setg -al - +its blocks · the visits so far · the path · the loops' turns + + + + + + + + + + + + + + + + + + + + + + + + + + +5 + turns +5 + turns + ++12 +×6 + ++1e +×6 + ++24 +×11 + ++5d +×5 + ++97 +×5 + ++99 +×5 + ++2f +×11 + ++56 +×11 + ++5f +swap +×5 + ++0 +×1 + ++a7 + + + +sort.c +lines 9 to 14 of 22 +9 +void +sort +( +int +n +) +{ +10 +for +( +int +i += +1 +; +i +< +n +; +i ++ ++ +) +{ +11 +int +j += +i +; + + +12 +while +( +j +> +0 +& +& +a +[ +j +- +1 +] +> +a +[ +j +] +) +{ + +13 +swap +( +& +a +[ +j +- +1 +] +, +& +a +[ +j +] +) +; + +14 +j +- +- +; + + + +disassembly +sort 4011 -a3 -mov -[rbp - 0xd], al -7fffffffecd3 -◂ -1 - +9d +12 +cmp +eax, [rcx + rdx*4] 4011 -a6 -mov -al, [rbp - 0xd] -7fffffffecd3 -◂ -1 - +a0 +setg +al + 4011 -a9 -test -al, 1 -1 - : -1 - -zf - - - +a3 +mov +[rbp - 0xd], al +7fffffffecd3 +◂ +1 + 4011 -ab -jne -4011af -taken - · reads zf +a6 +mov +al, [rbp - 0xd] +7fffffffecd3 +◂ +1 + 4011 -ad -jmp -4011e7 +a9 +test +al, 1 +1 + : +1 + +zf + + + 4011 -af -13 -mov -eax, [rbp - 0xc] +ab +jne +4011af +taken + · reads zf 4011 -b2 -sub -eax, 1 +ad +jmp +4011e7 4011 -b5 -cdqe - +af +13 +mov +eax, [rbp - 0xc] 4011 -b7 -lea -rdi, [rip + 0x2e52] +b2 +sub +eax, 1 4011 -be -shl -rax, 2 +b5 +cdqe + 4011 -c2 -add -rdi, rax - -×11 - -×5 - -×5 - - - -registers -stack -heap -code -data -rwx - -read-only - -rbx -0 -r8 -7ffff7e19680 -r9 -7ffff7e1afa0 -r10 -7fffffffea60 - - - - - -r11 -7ffff7ffca90 - - - - - -r12 -7fffffffee38 - - - - - -r13 -1 -r14 -7ffff7ffd000 - - - - - -r15 -403e10 - - - - - -rax -1 -rcx -404010 - - -0x900000004 -rdx -4 -rsi -404024 - - -0x1f0000001a -rdi -404020 - - -0x1a00000005 -rbp -7fffffffece0 - - -7fffffffed00 - - -7fffffffedb0 - - -7fffffffee10 - - -0 -rsp -7fffffffecd0 - - -0x401000000 - - -rip -4011ab -sort+91 -cf - -pf - -af -zf -sf - -IF -df -of - - - -stack -twelve words from rsp · the frames they belong to -rsp - -+0 -j, high half +b7 +lea +rdi, [rip + 0x2e52] + +×11 + +×5 + +×5 + + + +registers +stack +heap +code +data +rwx + +read-only + +rbx +0 +r8 +7ffff7e19680 +r9 +7ffff7e1afa0 +r10 +7fffffffea60 + + + + + +r11 +7ffff7ffca90 + + + + + +r12 +7fffffffee38 + + + + + +r13 +1 +r14 +7ffff7ffd000 + + + + + +r15 +403e10 + + + + + +rax +1 +rcx +404010 + + +0x900000004 +rdx +4 +rsi +404024 + + +0x1f0000001a +rdi +404020 + + +0x1a00000005 +rbp +7fffffffece0 + + +7fffffffed00 + + +7fffffffedb0 + + +7fffffffee10 + + +0 +rsp +7fffffffecd0 + + +0x401000000 + + +rip +4011ab +sort+91 +cf + +pf + +af +zf +sf + +IF +df +of + + + +stack +twenty words from rsp · the frames they belong to +rsp + ++0 +j, high half +7fffffffe +cd0 + + +0x401000000 ++8 +i, n +7fffffffe +cd8 + + +0x800000006 +rbp + ++10 +saved rbp +7fffffffe +ce0 + + +7fffffffed00 + + + + + ++18 +7fffffffe +ce8 + + +401219 +main+25 ++20 +7fffffffe +cf0 + + +0 ++28 +7fffffffe +cf8 + + +0 ++30 +saved rbp +7fffffffe +d00 + + +7fffffffedb0 + + + + + ++38 +7fffffffe +d08 + + +7ffff7c27781 +libc+27781 ++40 7fffffffe -cd0 - - -0x401000000 -+8 -i, n +d10 + + +7ffff7fe0c60 +ld.so+22c60 ++48 7fffffffe -cd8 - - -0x800000006 -rbp - -+10 -saved rbp +d18 + + +7fffffffee38 + + + + + ++50 7fffffffe -ce0 - - -7fffffffed00 - - - - - -+18 +d20 + + +0x1f7fbe000 ++58 7fffffffe -ce8 +d28 -401219 -main+25 -+20 +401200 +main+0 ++60 7fffffffe -cf0 - - -0 -+28 +d30 + + +7fffffffed70 + + + + + ++68 7fffffffe -cf8 - - -0 -+30 -saved rbp +d38 + + + + + ++70 7fffffffe -d00 - - -7fffffffedb0 - - - - - -+38 +d40 + + +0 ++78 7fffffffe -d08 - - -7ffff7c27781 -libc+27781 -+40 +d48 + + +0x455b402647827406 ++80 7fffffffe -d10 +d50 -7ffff7fe0c60 -ld.so+22c60 -+48 +7fffffffee38 + + + + + ++88 7fffffffe -d18 - - -7fffffffee38 - - - - - -+50 +d58 + + +1 ++90 7fffffffe -d20 - - -0x1f7fbe000 -+58 +d60 + + +7ffff7ffd000 ++98 7fffffffe -d28 +d68 -401200 -main+0 - - - -sort - - - -main - - -libc.so.6+27781 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +403e10 + + + +sort + + + +main + + +libc.so.6+27781 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - + - + - - + + - + - + - - + + - - + + + - - + - - + + - - + - - + - + - + - - + + - + + - + + - - + + - + - + + - + - - + + - + - + - - + + - - + - - + - - + + - + + - - - + + - + + - + + - + + - - + + - - + + - + - + - + - - + + - + - + - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - + - + @@ -746,135 +876,128 @@ - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - - - - - - - - - + + moment 434 of 1905 diff --git a/design/mock/42-frame-layouts.png b/design/mock/42-frame-layouts.png index ab9cece..56ba531 100644 Binary files a/design/mock/42-frame-layouts.png and b/design/mock/42-frame-layouts.png differ diff --git a/design/mock/43-graph-forms.png b/design/mock/43-graph-forms.png index 1775fd6..e5ff83c 100644 Binary files a/design/mock/43-graph-forms.png and b/design/mock/43-graph-forms.png differ diff --git a/design/mock/43-graph-forms.svg b/design/mock/43-graph-forms.svg index 6ec334b..0b857bc 100644 --- a/design/mock/43-graph-forms.svg +++ b/design/mock/43-graph-forms.svg @@ -1,311 +1,210 @@ - + - -sort's graph, four ways -The same moment in each (the 11th compare: 17 > 5, jne about to take the swap); the lens's scale, mono 20. Veiled: what falls outside the box the frame gives the lens. -1 -present: layers, boxes, square lanes -ten layers, 400 high: past the lens's 296 (veiled), so it pans; a third of its width + +the graph's two forms +At the lens's scale, mono 20; each in the pane the `blocks` split gives it, 880 by 344. Every number is the run's by the moment shown; veiled: what a pane must pan to. +1 +rings: sort at the 11th compare +each loop a ring, the inner touching the outer at its header; ways out down the tangent; whole in 880 by 344 - + the blocks of sort -its blocks · the visits · the path - - - - - - - - - - - - - - - - - - - - - - -×5 - - - - -×5 - - -+0 -×1 - - -+12 -×6 - - -+1e -×6 - - -+24 -×11 - - -+2f -×11 - - -+56 -×11 - - -+5d -×5 - - -+5f -×5 - - -+97 -×5 - - -+99 -×5 - - -+a7 - +its blocks · the visits so far · the path · the loops' turns + + + + + + + + + + + + + + + + + + + + + + + + + + +5 + turns +5 + turns + ++12 +×6 + ++1e +×6 + ++24 +×11 + ++5d +×5 + ++97 +×5 + ++99 +×5 + ++2f +×11 + ++56 +×11 + ++5f +swap +×5 + ++0 +×1 + ++a7 2 -the same layers, rounded -pills and round corners: smoother, and just as tall +layers: the same moment +the loops as lanes; 400 high, so it pans in 344 (veiled): for loops, rings the blocks of sort -its blocks · the visits · the path - - - - - - - - - - - - - - - - - - - - +its blocks · the visits so far · the path + + + + + + + + + + + + + + + + + + + + ×5 - - + + ×5 - + +0 -×1 - +×1 + +12 -×6 - +×6 + +1e -×6 - +×6 + +24 -×11 - +×11 + +2f -×11 - +×11 + +56 -×11 - +×11 + +5d -×5 - +×5 + +5f -×5 - +swap +×5 + +97 -×5 - +×5 + +99 -×5 - +×5 + +a7 - -3 -rings -each loop a circle its blocks sit on, the inner inside the outer: 420 high, past the band's 200 (veiled) - - - -the blocks of sort -its blocks · the visits · the path · the loops' turns - - - - - - - - - - - - - - - - - - - - - - - - - - -×5 -×5 - -+0 -×1 - -+12 -×6 - -+1e -×6 - -+24 -×11 - -+2f -×11 - -+56 -×11 - -+5d -×5 - -+5f -×5 - -+97 -×5 - -+99 -×5 - -+a7 - -swap - -What each costs -1 The tools' picture. Tall by nature: a layer a block, - so it pans in a short pane, and leaves the width. -2 Rounding the corners does not change the shape. -3 The most circular, and a loop is a ring; but rings - want a square pane, a loop's way out is a chord - across them, and pills on its sides sit across it. -4 The track. A line of blocks as they run, each loop - an arch over its own blocks: a closed shape, its - turns at its centre; a jump past blocks a dip - under them. Wide and short: 11 blocks in 1622 - by 150, whole. Its order is the disassembly's, - which is under the source; run down, it is the - map's column with its rows. -4 -the track: recommended -the band across the frame, 1792 by 200: the whole graph, no pan - - - -the blocks of sort -its blocks · the visits · the path · the loops' turns - - - - - - - - - - - - - - - - - - - - - - - - - - -×5 -×5 - -+0 -×1 - -+12 -×6 - -+1e -×6 - -+24 -×11 - -+2f -×11 - -+56 -×11 - -+5f -×5 - -swap - -+5d -×5 - -+97 -×5 - -+99 -×5 - -+a7 -Ink in 3 and 4: never taken in the whole run, dashed rule (j > 0 failing); not yet, rule (the way out); taken, dim; the last three, the trail's golds. 1 and 2 keep the layers' ink: never taken, rule. + +2 +layers: libc's open at its syscall +a tree of branches and no loop (rings has none to draw, and is this); what is not reached yet folded, dashed + + + +the blocks of open · libc.so.6 +its blocks · the visits so far · the path + + + + + + + + + + + + + + + + + + + + + ++0 +×1 + ++29 +×1 + ++3b +×1 + ++d0 + ++f0 +×1 + ++5b … +· 7 + ++be … +· 8 +Which, and why +1 Rings, the first form. A loop is a ring and the mark going + round it is the picture of iteration; its turns at its + centre. Nested loops: rings touching at the header. +2 Layers, the second, for a function of branches: the path + reads down, and a fork is two columns. Rings with no + loop is this. For loops it is tall and pans. + The track is withdrawn: a ring says a loop, a layer a + branch; a line of blocks said neither, and its arches + were rings flattened to fit a band. +Nothing from after the moment: counts so far; an edge or +a block not reached yet is quiet (rule, page, no count); +open's folds are what it has not reached yet, and open +as the run gets there. +Ink: not reached so far, rule; taken so far, dim; the last three, the trail's golds, the newest 3. A fold, dashed. No count before a block's first visit. diff --git a/design/mock/frame.py b/design/mock/frame.py index 15b3933..209116f 100644 --- a/design/mock/frame.py +++ b/design/mock/frame.py @@ -1,11 +1,11 @@ #!/usr/bin/env python3 """The working frame reworked: the disassembly under the source in every split, the registers a scene does not -move folded three to a row, the stack given what that frees, and the `blocks` lens's drawing across the band. +move folded three to a row, the stack given what that frees, and the `blocks` lens's rings over the program column. python3 -B frame.py # 40-frame-beside, 41-frame-subject, 25-blocks-lens (.svg), 42-frame-layouts.png 40 and 41 are mocks 9 and 11 in the reworked frame (the same recording of targets/list, the same moments, each -pane's minimap from the map as map.py draws it); 25 is sort with the `blocks` lens (graph.py's track, the stop in +pane's minimap from the map as map.py draws it); 25 is sort with the `blocks` lens (graph.py's rings, the stop in sort-dbg.txt); 42 sets the three layouts weighed this round side by side, each as the list's `subject` and sort's `blocks`, at a third of their size: A (recommended) folds the quiet registers, B keeps all seventeen and gives the source's rows to the disassembly, C sets the registers in two columns. @@ -26,15 +26,17 @@ from context import (PAGE, RAISED, RULE, VELLUM, BRIGHT, DIM, FAINT, GOLD, HEAP, HERE = G.HERE TOP, FOOT = 48, 888 -WORDS = {6: "six", 8: "eight", 10: "ten", 11: "eleven", 12: "twelve", 13: "thirteen", 14: "fourteen", 15: "fifteen"} +WORDS = {6: "six", 8: "eight", 10: "ten", 11: "eleven", 12: "twelve", 13: "thirteen", 14: "fourteen", 15: "fifteen", + 20: "twenty", 22: "twenty-two"} # ---- the splits ------------------------------------------------------------------------------------------------- # What a scene gives its lens, and the program column's rows under it: (drawing, view, source, disassembly). The -# `blocks` lens has no view: its drawing is the band across both columns. -SPLITS = {"none": (0, 0, 14, 17), "beside": (152, 152, 8, 17), "subject": (296, 200, 8, 11), "blocks": (200, 0, 8, 15)} +# `blocks` lens has no view: its drawing (rings, 880 by 344) is over the program column, and the state column is +# the registers' and the stack's from the top. +SPLITS = {"none": (0, 0, 14, 17), "beside": (152, 152, 8, 17), "subject": (296, 200, 8, 11), "blocks": (344, 0, 6, 11)} LAYOUTS = { "A": dict(regs="fold", src=None, dis=None), # the splits above - "B": dict(regs="all", src=6, dis=lambda d: d + 2), # all seventeen rows; the source gives two rows + "B": dict(regs="all", src=6, dis=lambda d, s: d + s - 6), # all seventeen rows; the source gives to six "C": dict(regs="two", src=None, dis=None), # the registers in two columns of eight, rip across } @@ -44,22 +46,23 @@ def boxes(split, layout, quiet): band, view, src, dis = SPLITS[split] L = LAYOUTS[layout] if L["src"] is not None and split != "none": - src, dis = L["src"], L["dis"](dis) + src, dis = L["src"], L["dis"](dis, src) regs = {"fold": C.reg_rows(quiet), "all": 17, "two": 9}[L["regs"]] out = {} y = TOP + (band + 12 if band else 0) out["source"] = (64, y, ph(src)) out["disasm"] = (64, y + ph(src) + 12, ph(dis)) assert out["disasm"][1] + out["disasm"][2] == FOOT or split == "none", (split, layout, out) - ys = TOP + (view + 12 if view else band + 12 if split == "blocks" else 0) + ys = TOP + (view + 12 if view else 0) out["registers"] = (976, ys, ph(regs)) yk = ys + ph(regs) + 12 - out["stack"] = (976, yk, FOOT - yk) + words = (FOOT - yk - TAG - 8) // ROW + out["stack"] = (976, FOOT - ph(words), ph(words)) # a panel is 32 + 24n: what is left over is above it if band: out["drawing"] = (64, TOP, band) if view: out["view"] = (976, TOP, view) - return out, regs, (FOOT - yk - TAG - 8) // ROW + return out, regs, words # ---- the registers in two columns (layout C) ------------------------------------------------------------------ @@ -256,33 +259,7 @@ SORT_REGS = [("rax", [], ("int", 1)), ("rbx", [], ("int", 0)), ("rcx", [(0x40401 SORT_FLAGS = [("CF", 0, 0), ("PF", 0, 1), ("AF", 0, 1), ("ZF", 0, 0), ("SF", 0, 0), ("IF", 1, 0), ("DF", 0, 0), ("OF", 0, 0)] SORT_QUIET = ("rbx", "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15") # sort moves the other eight SORT_SRC = open(HERE + "/../../anim/tools/sort.c").read().split("\n") -TEXT = G.read_dis("sort-clang.dis") # the program's text: swap, sort, main -FUNC = lambda a: "swap" if a < 0x401150 else "sort" if a < 0x401200 else "main" - - -def sort_disasm(g, y, n): - """n rows round the pc; each block's first row under a rule, its visits ranged right in the annotation's room - (the pill's count, in its digits); the trail's three rows and the pc's with what they did.""" - i = [r[0] for r in TEXT].index(G.PC) - lo = max(0, min(i - n // 2, len(TEXT) - n)) - st = G.sort_state(G.UPTO, G.PC, G.TRAIL_ROWS) - notes = dict(G.NOTES) - notes[0x4011a3] = [("7fffffffecd3 ", STACK), ("◂ ", FAINT), ("1", VELLUM)] - rows = [] - for a, ln, mn, ops, t, callee in TEXT[lo:lo + n]: - state = "cur" if a == G.PC else {0x4011a9: "trail0", 0x4011a6: "trail1", 0x4011a3: "trail2"}.get(a) - note = ("runs", notes[a]) if a in notes else ("text", callee, VELLUM) if mn == "call" else None - rows.append((a, ln, mn, [(t, CODE)] if t and (mn.startswith("j") or mn == "call") else [(ops, VELLUM)], - state, note)) - at = C.disasm(g, y, rows, "sort", 12) - for a in at: - if a in G.SORT_BL and a != "note": # a block's first row: the rule over it, its pill's digits - yy = at[a] - g.rect(C.LX + 2, yy, C.CW - 4, 2, RULE) - n_ = st["blocks"][a]["count"] - g.t(C.LX + C.CW - 12, b(yy), "×%d" % n_, S, FAINT, MONO, "end") - line12 = [at[r[0]] for r in rows if r[1] == 12 and r[0] < 0x4011af] - return at, (min(line12), max(line12) + ROW), lo +TEXT, FUNC = G.TEXT, G.FUNC def sort_strips(g, bx, lo, n, words): @@ -313,19 +290,20 @@ def sort_frame(g, layout="A", strips=True): """Mock 25 in a layout: the `blocks` lens across the band, the source and the disassembly under it.""" bx, nregs, words = boxes("blocks", layout, SORT_QUIET) st = G.sort_state(G.UPTO, G.PC, G.TRAIL_ROWS, G.NOTES) - G.track_lens(g, 64, TOP, 1792, 200, G.SORT_BL, G.SB[0], G.SORT_BASE, st, "the blocks of sort") + G.rings(g, 64, TOP, 880, 344, G.SORT_BL, G.SORT_BASE, st, G.SORT_RINGS, "the blocks of sort") src, dis = (bx["source"][2] - 32) // ROW, (bx["disasm"][2] - 32) // ROW C.LX, C.RX = 64, 976 M.strip(strips) first = max(1, 12 - src // 2) ys = C.source(g, bx["source"][1], src, SORT_SRC, first, 12, [14, 13], "sort.c", 22) - at, run, lo = sort_disasm(g, bx["disasm"][1], dis) + at, run, lo = G.sort_disasm(g, bx["disasm"][1], dis) M.strip(False) draw_registers(g, layout, bx["registers"][1], SORT_REGS, SORT_FLAGS, {}, SORT_QUIET) M.strip(strips) C.RX = 976 roles = {0: ("j, high half", VELLUM), 1: ("i, n", VELLUM), 2: ("saved rbp", DIM), 6: ("saved rbp", DIM)} - C.stack(g, bx["stack"][1], sort_slots(words), [("sort", 0, 3), ("main", 4, 7), ("libc.so.6+27781", 8, 29)], + C.stack(g, bx["stack"][1], sort_slots(words), [("sort", 0, 3), ("main", 4, 7), ("libc.so.6+27781", 8, 29), + ("__libc_start_main+137", 30, 41)], rsp=RSP_S, roles={k: v for k, v in roles.items() if k < words}, note="%s words from rsp" % WORDS[words]) M.strip(False) C.thread(g, ys, [run]) @@ -392,7 +370,7 @@ def sheet(out): "list, subject" if kind == "subject" else "sort, blocks", src, dis, regs, words) d.text((x, y + 352), lab, font=body, fill="#eee6d2") if kind == "blocks": - d.text((x, y + 378), "the graph across the band: 1792 by 200, whole", font=body, fill="#9aa6d9") + d.text((x, y + 378), "rings over the program column, 880 by 344: whole", font=body, fill="#9aa6d9") else: d.text((x, y + 378), "the drawing 296 and its view of 7 over the state column", font=body, fill="#9aa6d9") s.save(HERE + "/" + out) diff --git a/design/mock/graph.py b/design/mock/graph.py index 6062fa9..083842e 100644 --- a/design/mock/graph.py +++ b/design/mock/graph.py @@ -1,19 +1,20 @@ #!/usr/bin/env python3 -"""The disassembly's other form: a function as a graph of its basic blocks, with what the run did on it. +"""The disassembly's other form: a function as a graph of its basic blocks, with what the run has done on it by +the moment shown, and nothing after. - python3 -B graph.py # 22-graph-sort, 23-graph-open, 24-graph-strip, 43-graph-forms (.svg) + python3 -B graph.py # 22-graph-sort, 24-graph-strip, 43-graph-forms (.svg) # (25, the `blocks` lens in the working frame, is frame.py's) -The form is the track: the blocks in a line in the order they run, each loop closing over the line as an arch -whose blocks sit on its floor, a forward jump that skips blocks dipping under them. Across in the lens's band, -down on the map, where the blocks are cards that carry their rows. The layered form it replaced (`silhouette`, -with `place` and `edges`) is kept for the comparison sheet, 43. +Two forms. `rings`, the first: each loop a ring its blocks sit on, clockwise from its header at the ring's left, +an inner loop a smaller ring touching its parent at its header, a loop's way out leaving along the ring's tangent; +what is outside every loop laid in layers. `layers`, the second, for a function that is a tree of branches: the +blocks in layers, pills and round corners. A block a pill either way (its offset, its visits so far). Data: sort as the scene builds it (clang -O0, anim/build.zig, less the instrumentation's calls): sort-clang.dis (objdump -dl), its path from `ztrace record --by insn --from sort` (the block leaders it hit), its stop in sort-dbg.txt. reverse from anim/tools/list.c (cc -O0), reverse-O0.dis, its path from `ztrace dbg` stepped by -instruction. libc's `open` from objdump of -/usr/lib/libc.so.6 (libc-open.dis), its path the one mock 16's run took. +instruction. libc's `open` from objdump of /usr/lib/libc.so.6 (libc-open.dis), its path the one mock 16's run +took. Every count is the path's up to the moment shown. """ import math import re @@ -129,102 +130,6 @@ def layers(bl, entry): return lay, back -# ---- a block, at the map's size: a head and insn rows -------------------------------------------------------- -X_OFF, X_LINE, X_MN, X_OPS = 72, 116, 128, 212 - - -def block_w(blk, base, note_w=0): - """As wide as its widest row as drawn (the size words gone, a width's cells in their place), 300 at least.""" - ops = [len(re.sub(r"\b\w+ ptr ", "", r[3])) + (3 if " ptr " in r[3] else 0) for r in blk.rows] - return max(300, X_OPS + max(ops) * A + 24 + note_w) - - -def fold_rows(rows, keep): - """A block longer than 16 rows: its first four and last four, the middle one `more` row.""" - if len(rows) <= 16 or keep: - return rows - return rows[:4] + [None] + rows[-4:] - - -def draw_block(g, x, y, w, blk, base, st): - """st: count (visits), cur (the pc's address in it), trail (ran rows), notes {address: note}, cur_line.""" - if hasattr(blk, "folded"): # blocks the whole recording never reached: one dashed box, no rows - h = TAG + ROW + PAD - g.rect(x, y, w, h, PAGE) - g.frame(x, y, w, h, RULE, 2, "12 8") - g.t(x + 12, b(y), "+%x to +%x" % (blk.rows[0][0] - base, blk.rows[-1][0] - base), S, FAINT, MONO) - g.t(x + w - 12, b(y), "%d blocks never reached" % len(blk.folded) if len(blk.folded) > 1 else "never reached", - 18, FAINT, "sans", "end") - g.t(x + 12, b(y + TAG), blk.name, 18, DIM, "sans") - return h, {} - rows = fold_rows(blk.rows, st.get("cur")) - h = TAG + len(rows) * ROW + PAD - reached = st.get("count", 0) > 0 - g.rect(x, y, w, h, PAGE) - g.rect(x, y, w, TAG, RAISED if reached else PAGE) - g.frame(x, y, w, h, GOLD if st.get("cur") else RULE, 2) # not reached yet: plain, no count - ink = CODE - C.addr(g, x + 12, y, blk.a, ink) - lines = sorted({r[1] for r in blk.rows if r[1]}) - if lines: - g.t(x + 12 + len("%x" % blk.a) * A + 16, b(y), "line %d" % lines[0] if len(lines) == 1 else - "lines %d to %d" % (lines[0], lines[-1]), 18, FAINT, "sans") - if reached: - g.t(x + w - 12, b(y), "×%d" % st["count"], S, VELLUM, MONO, "end") - yy, last_line, at = y + TAG, None, {} - for r in rows: - if r is None: - C.more(g, x + X_OFF - 36, yy) - g.t(x + X_MN, b(yy), "%d rows" % (len(blk.rows) - 8), S, FAINT, MONO) - yy += ROW - continue - a, ln, mn, ops, t, callee = r - at[a] = yy - dim_ = False - if a == st.get("cur"): - g.path(f"M{x + 20},{yy + 12} l-10,-6 v12 Z", fill=C.current_row(g, x + 2, yy, w - 4, 24)) - elif a in st.get("trail", []): - g.rect(x + 2, yy + 1, 4, ROW - 2, TRAIL[st["trail"].index(a)]) - g.t(x + X_OFF, b(yy), "+%x" % (a - base), S, FAINT if not dim_ else mix(FAINT, PAGE, 0.4), MONO, "end") - if ln and ln != last_line: - on = ln == st.get("cur_line") and st.get("cur") - g.t(x + X_LINE, b(yy), str(ln), S, GOLD if on else FAINT, BOLD if on else MONO, "end") - last_line = ln - fade = (lambda c: mix(c, PAGE, 0.55)) if dim_ else (lambda c: c) - g.t(x + X_MN, b(yy), mn, S, fade(FAINT if mn in ("nop", "endbr64") else KW), - MONO if mn in ("nop", "endbr64") else BOLD) - if t and (mn.startswith("j") or mn == "call"): - ex = C.addr(g, x + X_OPS, yy, t, fade(CODE)) - else: - ex = C.operands(g, x + X_OPS, yy, mn, ops, fade(VELLUM)) - note = st.get("notes", {}).get(a) - if note: - nx = max(ex + 2 * A, x + X_OPS + 20 * A) - for s_, ink_ in note: - if ink_ == "chip": - g.rect(nx, yy + 2, 32, 20, RAISED) - g.t(nx + 16, b(yy), s_, S, BRIGHT, BOLD, "middle") - nx += 38 - else: - g.t(nx, b(yy), s_, S, ink_, MONO) - nx += len(s_) * A - if mn == "call" and callee: # a call that comes back: out of the block's side and in again a row down - hx = x + w - g.path(f"M{hx},{yy + 12} h14 q6,0 6,6 v12 q0,6 -6,6 h-8", fade(DIM) if reached else RULE, 2) - g.path(f"M{hx},{yy + 36} l8,-4 v8 Z", fill=fade(DIM) if reached else RULE) - g.t(hx + 28, b(yy) + 12, callee, S, fade(VELLUM), MONO) - if st.get("split") and r is rows[-1] and not st.get("cur"): # a conditional's two ways, counted, in words - tk, nt = st["split"] - g.t(max(ex + 2 * A, x + X_OPS + 10 * A), b(yy), "taken %d · not %d" % (tk, nt), S, FAINT, MONO) - yy += ROW - if blk.ret: # the way out: a stub and a bar under the block - cx = x + w / 2 - g.rect(cx - 1, y + h, 2, 14, DIM if reached else RULE) - g.rect(cx - 14, y + h + 14, 28, 3, DIM if reached else RULE) - return h, at - - -# ---- the graph: placement and edges ----------------------------------------------------------------------- def arrow(g, pts, *a, **k): """gen.arrow, its repeated and straight-through points dropped.""" q = [] @@ -253,7 +158,7 @@ def edges(g, bl, lay, back, pos, widths, heights, lh, ly, gap, st, base, lane_x0 """Every edge: forward ones down from the bottom by the side their target lies on, along the gap's middle, down into the target's top; one that would cross a block runs in the right channel; a back edge leaves the bottom, goes out to its loop's lane on the left, climbs it and enters its header's head from the side: the one thing - that climbs. Ink: never taken `rule`; taken in the run `dim`; the last three taken the trail's golds.""" + that climbs. Ink by the moment shown: not taken yet `rule`; taken `dim`; the last three the trail's golds.""" sw0 = 2 trail = st.get("edge_trail", []) counts = st.get("edge_counts", {}) @@ -324,243 +229,6 @@ def run_state(bl, path, upto, base): return cnt, ec, trail -# ---- the data: sort as the scene builds it ------------------------------------------------------------------ -SORTC = [r for r in read_dis("sort-clang.dis") if 0x401150 <= r[0] < 0x401200] -SORT_BASE = 0x401150 -SORT_BL = blocks(SORTC, SORT_BASE) -SB = sorted(SORT_BL) -# the block leaders the run hit, from sort's entry to its return: ztrace record --by insn --from sort, clang -O0 -SORT_PATH = [SORT_BASE + int(o, 16) for o in ( - "0 12 1e 24 2f 56 5d 97 99 12 1e 24 2f 56 5d 97 99 12 1e 24 2f 56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5f 24 2f " - "56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5f 24 2f 56 5f 24 2f 56 5f 24 2f 56 " - "5f 24 2f 56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5f 24 2f 56 5d 97 99 12 a7").split()] -O = lambda off: SORT_BASE + off -NEVER = {(a, t) for a in SORT_BL for t, _ in SORT_BL[a].out} - set(zip(SORT_PATH, SORT_PATH[1:])) - - -def sort_state(upto, cur, trail_rows, notes=None, cur_line=12): - cnt, ec, trail = run_state(SORT_BL, SORT_PATH, upto, SORT_BASE) - blk = {a: {"count": cnt.get(a, 0)} for a in SORT_BL} - if cur: - ca = max(a for a in SORT_BL if a <= cur) - blk[ca].update(cur=cur, trail=trail_rows, notes=notes or {}, cur_line=cur_line) - return {"blocks": blk, "edge_counts": ec, "edge_trail": trail, "never": NEVER} - - -# the 11th time through the compare: i = 6, j = 4, a[3] = 17 against a[4] = 5; the stop is the jne after it -# (sort-dbg.txt). Five swaps so far, five turns of each loop. -UPTO = [i for i, a in enumerate(SORT_PATH) if a == O(0x56)][10] + 1 -PC = 0x4011ab -TRAIL_ROWS = [0x4011a9, 0x4011a6, 0x4011a3] -NOTES = {0x4011a6: [("7fffffffecd3 ", STACK), ("◂ ", FAINT), ("1", VELLUM)], - 0x4011a9: [("1", VELLUM), (" : ", FAINT), ("1", VELLUM), (" ", FAINT), ("zf", DIM)], - 0x4011ab: [("taken", VELLUM), (" · reads zf", FAINT)]} - - -def frame_sort_map(name): - """Mock 22: on the map, the disassembly column as sort's track, one column wide (1024 to 1904), beside the - source whole: the cards on their spine, the loops' lanes on the left, the jumps past cards on the right.""" - gen.W, gen.H = 1980, 1860 - g = Svg() - src = open(HERE + "/../../anim/tools/sort.c").read().split("\n") - C.LX = 112 - C.source(g, 96, 22, src, 1, 12, [14, 13], "sort.c", 22) - C.LX = 64 - g.t(112, 60, "the map: sort's disassembly as its track, in the second column (1024 to 1904), at the 11th compare", - 22, DIM, "sans") - st = sort_state(UPTO, PC, TRAIL_ROWS, NOTES) - hgt, ats, _ = track_map(g, 1024, 96, 880, SORT_BL, SB[0], SORT_BASE, st, "disassembly · sort", - "its blocks · visits · the edges taken · the loops' turns", notes_w=17 * A) - print("22: the track on the map is %d high; the map's stage holds %d" % (hgt, 1688)) - g.rect(112, 1784, 1792, 2, RULE) - g.t(112, 1808, "the map's stage ends at 1784", 18, FAINT, "sans") - g.save(name) - - -# ---- libc's open: unreached blocks folded ----------------------------------------------------------------- -OPEN = read_dis("libc-open.dis", lines=False) -OPEN_BASE = 0x110ec0 -L = 0x7ffff7c00000 - - -def rebase(rows): - return [(a + L, ln, mn, ops, (t + L) if t else None, callee) for a, ln, mn, ops, t, callee in rows] - - -OPEN_BL = blocks(rebase(OPEN), OPEN_BASE + L) -OPEN_PATH = [a + L for a in (0x110ec0, 0x110ee9, 0x110efb, 0x110fb0, 0x110fca, 0x110fd2, 0x110fd4, 0x110fe3)] - - -def fold_unreached(bl, path, groups): - """Blocks the run never reached, a connected run of them one box: `5 blocks not reached`.""" - out = {a: bl[a] for a in bl if a in path} - for name, members in groups: - rows = [r for m in members for r in bl[m].rows] - fb = Block(name, rows) - fb.folded = members - out[members[0]] = fb - rep = {m: ms[0] for _, ms in groups for m in ms} - for a, blk in list(out.items()): - seen = [] - for t, k in (blk.out if not hasattr(blk, "folded") else [o for m in blk.folded for o in bl[m].out]): - t2 = rep.get(t, t) - if t2 != a and t2 in out and (t2, k) not in seen and t2 not in [s_ for s_, _ in seen]: - seen.append((t2, k)) - blk.out = seen - blk.ret = blk.ret if not hasattr(blk, "folded") else False - return out - - -def frame_open_map(name): - """Mock 23: libc's open, 19 blocks, of which the run reached 8; the 11 it did not are folded into five cards by - what they are. The pc is at the `syscall` (mock 16's moment 4): the blocks after it are reached later.""" - gen.W, gen.H = 1008, 1640 - g = Svg() - o = lambda x: x + L - groups = [("the O_CREAT path: the mode from the varargs", [o(0x110f90)]), - ("multi-threaded: a cancellable call", [o(0x110f1b), o(0x110f23), o(0x110f2b), o(0x110f6d)]), - ("an error: errno set, -1 returned", [o(0x110fe8), o(0x110f79), o(0x110f7e)]), - ("cancelled", [o(0x110ff6), o(0x111009)]), - ("the canary broken", [o(0x110fec), o(0x110ff0)])] - groups = [(n, [m for m in ms if m in OPEN_BL]) for n, ms in groups] - bl = fold_unreached(OPEN_BL, OPEN_PATH, groups) - st = {"blocks": {a: {"count": 1} for a in OPEN_PATH}} - st["blocks"][o(0x110fb0)].update(cur=o(0x110fc5), trail=[o(0x110fc0), o(0x110fb9), o(0x110fb6)], - notes={o(0x110fc5): [("openat", BRIGHT), (" nr 257", FAINT)]}) - st["edge_counts"] = Counter(zip(OPEN_PATH[:4], OPEN_PATH[1:4])) - st["edge_trail"] = list(reversed(list(zip(OPEN_PATH[:4], OPEN_PATH[1:4])))) - for a in OPEN_PATH[4:]: - st["blocks"][a]["count"] = 0 # not yet: the run is at the syscall - for _, ms in groups: - st["blocks"][ms[0]] = {"count": 0} - g.t(64, 60, "the map: libc's open as its track · 19 blocks, the run reached 8; the 11 never reached folded", 22, - DIM, "sans") - hgt, _, _ = track_map(g, 64, 96, 880, bl, OPEN_PATH[0], OPEN_BASE + L, st, "disassembly · open · libc.so.6", - "no source · 19 blocks · folded: 11 never reached", notes_w=18 * A) - print("23: %d high" % hgt) - g.save(name) - - -# ---- reverse: a loop's turn, as a strip ------------------------------------------------------------------- -REV = read_dis("reverse-O0.dis") -REV_BASE = 0x401188 -REV_BL = blocks(REV, REV_BASE) -RB = sorted(REV_BL) -R0, R1, R2, R3 = RB -REV_PATH = [R0, R2, R1, R2, R1, R2, R1, R2, R3] - - -def frame_strip(name): - """Mock 24: reverse's loop in the lens, four instants: the condition about to be decided; the edge taken, the - mark on it; the turn, the mark on the arch over the loop's blocks, its count struck; the way out, under.""" - gen.W, gen.H = 1920, 600 - g = Svg() - inst = [ - ("1", "the condition", "the pc on jne in the test's block, the second time; its two ways out", 4, 0x4011ce, None), - ("2", "the edge taken", "taken: along the line to the body, the mark on the edge, landing", 4, None, - ((R2, R1), 0.55)), - ("3", "the loop's turn", "back over the arch to the test, the mark coming round; the count struck as it lands", 5, - None, ((R1, R2), 0.6)), - ("4", "the way out", "not taken, the fourth time: under the body to the exit, landed", 9, 0x4011d0, None), - ] - for k, (num, title, sub, upto, cur, moving) in enumerate(inst): - x, y = 64 + (k % 2) * 912, 40 + (k // 2) * 280 - g.t(x, y + 24, num, 28, GOLD, "sansb") - g.t(x + 28, y + 24, title, 28, VELLUM, "sansm") - g.t(x, y + 52, sub, 18, FAINT, "sans") - path = REV_PATH[:upto] + ([moving[0][1]] if moving else []) - cnt, ec, trail = run_state(REV_BL, path, len(path), REV_BASE) - if moving: # the mark is on its edge: the target not yet entered, the edge lit - cnt[moving[0][1]] -= 1 - st = {"blocks": {a: {"count": cnt.get(a, 0)} for a in REV_BL}, "edge_counts": ec, "edge_trail": trail} - if cur: - ca = max(a for a in REV_BL if a <= cur) - st["blocks"][ca].update(cur=cur) - track_lens(g, x, y + 72, 880, 200, REV_BL, R0, REV_BASE, st, "the blocks of reverse", moving=moving, - struck=moving[0] if moving and moving[0] == (R1, R2) else None) - g.save(name) - - -# ---- the layered form, as the lens drew it before the track (the comparison sheet) ------------------------- -def silhouette(g, x, y, w, h, bl, entry, base, cols, st, title, rounded=False, pitch=300): - """The layered form without its text (the lens before the track): a block a box 24 high, as wide as its rows - (10 a row, 132 at least), its offset and visits; the pc's gold; edges and lanes as on the map, small. - rounded: the same layers with pills and round corners (the comparison sheet's second form).""" - lay, back = layers(bl, entry) - widths = {a: max(132, 60 + len(bl[a].rows) * 10) for a in bl} - heights = {a: 24 for a in bl} - nb = len(back) - x0 = x + 24 + nb * 10 + 16 - pos, lh, ly = place(bl, lay, cols, widths, heights, x0 + 60, y + TAG + 14, pitch, 12) - C.tag(g, x, y, w, h, title, focus=True, note="its blocks · the visits · the path") - edges(g, bl, lay, back, pos, widths, heights, lh, ly, 12, st, base, x + 24, max(pos[a][0] + widths[a] for a in bl) + 20, - small=True, radius=12 if rounded else None) - for a in bl: - s_ = st["blocks"].get(a, {}) - bx, by = pos[a] - cur = s_.get("cur") - if rounded: - pill(g, bx, by, widths[a], RAISED if s_.get("count") else PAGE, GOLD if cur else RULE, 3 if cur else 2) - else: - g.rect(bx, by, widths[a], 24, RAISED if s_.get("count") else PAGE) - g.frame(bx, by, widths[a], 24, GOLD if cur else RULE, 2 if not cur else 3) - g.t(bx + (12 if rounded else 8), b(by), "+%x" % (a - base), S, VELLUM if s_.get("count") else FAINT, MONO) - if s_.get("count"): - g.t(bx + widths[a] - (12 if rounded else 8), b(by), "×%d" % s_["count"], S, DIM, MONO, "end") - return pos, max(by for _, by in pos.values()) + 24 - y - - -# ---- the track ---------------------------------------------------------------------------------------------- -def loops_of(bl, entry): - """Layers and back edges as `layers` finds them, and each loop's blocks: a back edge's natural loop (its - header, and every block that reaches its latch without passing the header), loops of one header merged.""" - lay, back = layers(bl, entry) - preds = {a: [] for a in bl} - for a in bl: - for t, _ in bl[a].out: - preds[t].append(a) - loops = {} - for a, h in back: - body, todo = {h, a}, [a] - while todo: - n = todo.pop() - if n == h: - continue - for p in preds[n]: - if p not in body: - body.add(p) - todo.append(p) - loops.setdefault(h, set()).update(body) - return lay, back, loops - - -def track_order(bl, lay, loops): - """The line's order: as they run (by layer, then address), each loop's blocks together from its header, so - that a block outside a loop never sits on its floor; the blocks that return last.""" - def emit(nodes, header=None): - out, done = [], set() - for a in sorted(nodes, key=lambda a: (lay[a], a)): - if a in done: - continue - if a in loops and a != header and loops[a] <= nodes: - inner = emit(loops[a], a) - out += inner - done |= set(inner) - else: - out.append(a) - done.add(a) - return out - return emit(set(bl)) - - -def spans_levels(spans): - """Arches (or dips) by nesting: one that holds another is a level higher, so that none crosses another.""" - lv = {} - for s in sorted(spans, key=lambda s: s[1] - s[0]): - inner = [lv[o[2]] for o in spans if o[2] in lv and s[0] <= o[0] and o[1] <= s[1] and o[2] != s[2]] - lv[s[2]] = 1 + max(inner, default=0) - return lv - class Path: """An edge as drawn: straight runs and quarter circles, one family. Kept as points too, to measure it and to @@ -619,13 +287,6 @@ def draw_path(g, p, ink, sw, dash=None, hl=8, hw=8): gen.head_tri(g, x2, y2, ux, uy, ink, hl, hw) -def pill(g, x, y, w, fill, stroke, sw=2, dash=None): - """A block in the lens: a pill 24 high, its ends half circles.""" - a = (f'") - - def mark(g, p, f, ink=GOLD): """The current mark travelling an edge: the gold plaque, its point the way it goes.""" (mx, my), (ux, uy) = p.at(f) @@ -634,260 +295,183 @@ def mark(g, p, f, ink=GOLD): def edge_ink(e, st): - """Never taken in the whole recording: rule, dashed. Not yet: rule. Taken: dim. The last three: the trail's - golds, the newest 3 units.""" + """By the moment shown: not taken yet, `rule`; taken, `dim`; the last three taken, the trail's golds, the newest + 3 units. Nothing that needs the rest of the run.""" trail = st.get("edge_trail", []) if e in trail: return TRAIL[trail.index(e)], 3 if trail.index(e) == 0 else 2, None if st.get("edge_counts", {}).get(e, 0): return DIM, 2, None - return RULE, 2, "12 8" if e in st.get("never", ()) else None - - -TRACK = dict(gap=40, arch=52, arch_step=36, dip=44, dip_step=16, stub=10, port=16) - - -def track_lens(g, x, y, w, h, bl, entry, base, st, title, note="its blocks · the visits · the path · the loops' turns", - tag=True, moving=None, struck=None): - """The `blocks` lens: the function as a track across the band. A block a pill 24 high (its offset, its - visits; as long as its rows at 10 a row, the text's length at least) on one line, in the order they run; - an edge to the next block a straight run along the line; a loop's back edge an arch over its blocks, out of - its latch's top and down into its header's (the loop is the closed shape the arch and its floor make, its - turns at its centre); a forward jump past blocks a dip under them. Arches nest by level, 32 apart; dips 16. - moving: (edge, fraction): the mark on that edge. struck: an arch whose count is being struck. - Returns the edges' paths, and the line's y.""" - lay, back, loops = loops_of(bl, entry) - order = track_order(bl, lay, loops) - idx = {a: i for i, a in enumerate(order)} - - def text_of(a): - n = st["blocks"].get(a, {}).get("count", 0) - return "+%x" % (a - base), ("×%d" % n) if n else "" - pw = {a: max(24 + (len(text_of(a)[0]) + len(text_of(a)[1]) + 1) * A + 8, 10 * len(bl[a].rows) + 24) for a in order} - gap = TRACK["gap"] - total = sum(pw.values()) + gap * (len(order) - 1) - xs, xx = {}, x + (w - total) / 2 - for a in order: - xs[a] = xx - xx += pw[a] + gap - arches = [(idx[t], idx[a], (a, t)) for a, t in back] - dips = [(idx[a], idx[t], (a, t)) for a in order for t, _ in bl[a].out - if (a, t) not in back and idx[t] > idx[a] + 1] - al, dl = spans_levels(arches), spans_levels(dips) - H = lambda k: TRACK["arch"] + TRACK["arch_step"] * (k - 1) - D = lambda k: TRACK["dip"] + TRACK["dip_step"] * (k - 1) - top, foot = H(max(al.values(), default=1)), D(max(dl.values(), default=1)) - y0 = y + TAG + (h - TAG - top - foot) / 2 + top + return RULE, 2, None + + +def pill(g, x, y, w, fill, stroke, sw=2, dash=None): + """A block: a pill 24 high, its ends half circles.""" + a = (f'") + + +def calls_of(blk): + """The functions a block calls and that come back: named in its pill, after its offset.""" + if hasattr(blk, "folded"): + return "" + names = [r[5] for r in blk.rows if r[2] == "call" and r[5] and r[5] not in NORETURN] + return " ".join(names[:2]) + (" …" if len(names) > 2 else "") + + +def pill_text(bl, a, base, st): + """A block's words: its offset, the functions it calls, and its visits so far (none before its first).""" + if hasattr(bl[a], "folded"): + return "+%x …" % (bl[a].folded[0] - base), "· %d" % len(bl[a].folded) + n = st["blocks"].get(a, {}).get("count", 0) + return "+%x" % (a - base), ("×%d" % n) if n else "" + + +def pill_w(bl, a, base, st): + off, cnt = pill_text(bl, a, base, st) + c = calls_of(bl[a]) + return 24 + (len(off) + len(cnt) + 1 + (len(c) + 1 if c else 0)) * A + 8 + + +def draw_pill(g, x, y, bl, a, base, st, w=None): + """Reached so far: on `raised`, its offset primary, its visits. Not yet: on the page, its offset faint, no count. + A fold of blocks not reached yet: dashed, its span and how many. The pc's: framed gold, 3.""" + w = w or pill_w(bl, a, base, st) + s0 = st["blocks"].get(a, {}) + n, cur, fold = s0.get("count", 0), s0.get("cur"), hasattr(bl[a], "folded") + pill(g, x, y, w, RAISED if n else PAGE, GOLD if cur else RULE, 3 if cur else 2, "12 8" if fold else None) + off, cnt = pill_text(bl, a, base, st) + g.t(x + 12, b(y), off, S, VELLUM if n else FAINT, MONO) + c = calls_of(bl[a]) + if c: # a call is not an edge: the callee named in the pill, faint + g.t(x + 12 + (len(off) + 1) * A, b(y), c, S, FAINT, MONO) + if cnt: + g.t(x + w - 12, b(y), cnt, S, DIM if n else FAINT, MONO, "end") + return w + + +# ---- the second form: layers ------------------------------------------------------------------------------------ +def layered(g, x, y, w, h, bl, entry, base, cols, st, title, pitch=300, tag=True): + """`layers`: the blocks in layers by the longest path from the entry (from the code, not from the run), each + under its fall-through predecessor and a taken target to its right; a block a pill; edges down from the foot, + a back edge up its lane on the left; every corner round (12). Returns the pills' places and the height used.""" + lay, back = layers(bl, entry) + widths = {a: pill_w(bl, a, base, st) for a in bl} + heights = {a: 24 for a in bl} + x0 = x + 24 + len(back) * 10 + 16 + pos, lh, ly = place(bl, lay, cols, widths, heights, x0 + 60, y + TAG + 14, pitch, 12) if tag: - C.tag(g, x, y, w, h, title, focus=True, note=note) - paths = {} - s_, P = TRACK["stub"], TRACK["port"] - for a in order: - for t, kind in bl[a].out: - e = (a, t) - if e in back: # out of the latch's top, over, down into the header's - k, r = H(al[e]), H(al[e]) - 12 - s_ - xa, xt = xs[a] + pw[a] - P, xs[t] + P - p = (Path(xa, y0 - 12).to(xa, y0 - 12 - s_).arc(xa - r, y0 - k, r, False).to(xt + r, y0 - k) - .arc(xt, y0 - 12 - s_, r, False).to(xt, y0 - 12)) - elif idx[t] == idx[a] + 1: # to the next block: along the line - p = Path(xs[a] + pw[a], y0).to(xs[t], y0) - else: # past blocks: under them - k, r = D(dl[e]), D(dl[e]) - 12 - s_ - xa, xt = xs[a] + pw[a] - P, xs[t] + P - p = (Path(xa, y0 + 12).to(xa, y0 + 12 + s_).arc(xa + r, y0 + k, r, False).to(xt - r, y0 + k) - .arc(xt, y0 + 12 + s_, r, False).to(xt, y0 + 12)) - paths[e] = p - for e, p in sorted(paths.items(), key=lambda kv: kv[0] in st.get("edge_trail", ())): # the trail on top - ink, sw, dash = edge_ink(e, st) - draw_path(g, p, ink, sw, dash) - for a, t in back: # each loop's turns, at its centre: under its arch, over what it holds - e = (a, t) - n = st.get("edge_counts", {}).get(e, 0) - inner = max([H(al[o]) for o in al if al[o] < al[e]] + [12]) - cx, cy = (xs[t] + xs[a] + pw[a]) / 2, y0 - inner - (H(al[e]) - inner) * 0.4 # clear of the mark on the arch - s = "×%d" % n - if struck == e: - g.rect(cx - len(s) * A / 2 - 5, cy - 11, len(s) * A + 10, 22, C.SOFT) - g.t(cx, cy + 7, s, S, BRIGHT, BOLD, "middle") - elif n: - g.t(cx, cy + 7, s, S, DIM, MONO, "middle") - for a in order: - s0 = st["blocks"].get(a, {}) - n, cur = s0.get("count", 0), s0.get("cur") and not moving - pill(g, xs[a], y0 - 12, pw[a], RAISED if n else PAGE, GOLD if cur else RULE, 3 if cur else 2) - off, cnt = text_of(a) - g.t(xs[a] + 12, b(y0 - 12), off, S, VELLUM if n else FAINT, MONO) - if cnt: - g.t(xs[a] + pw[a] - 12, b(y0 - 12), cnt, S, DIM, MONO, "end") - for i, r_ in enumerate(bl[a].rows): # a call that comes back: a hook under the pill, out and in again - if r_[2] == "call" and r_[5] and r_[5] not in NORETURN: - cx = xs[a] + 16 + (pw[a] - 48) * i / max(len(bl[a].rows) - 1, 1) - g.path(f"M{cx:.1f},{y0 + 12:.1f} v6 a5,5 0 0 0 10,0 v-6", DIM if n else RULE, 2) - g.t(cx + 16, y0 + 34, r_[5], S, VELLUM if n else FAINT, MONO) - if moving: - mark(g, paths[moving[0]], moving[1]) - return paths, y0, xs, pw - - -def track_map(g, x, y, w, bl, entry, base, st, title, note, notes_w=0): - """The map's graph: the same track run down, a block a card that carries its rows (`draw_block`), the cards - in the line's order on one spine 40 in from their left; a back edge leaves its latch's left side and climbs - a lane on the left, 48 apart, into its header's head; a forward jump past cards leaves the source's right - side and goes down a channel on the right into its target's head. Every bend a quarter circle of 16; cards 10 - apart. The turns in the lobe between a lane and what it holds; a conditional's two ways counted in words in - its jump's row (`taken 5 · not 6`), where the pc's block has the jump's own annotation. - Returns the panel's height and each card's rows' y.""" - lay, back, loops = loops_of(bl, entry) - order = track_order(bl, lay, loops) - idx = {a: i for i, a in enumerate(order)} - fold = lambda a: hasattr(bl[a], "folded") - split_w = lambda a: (X_OPS + max(len("%x" % (bl[a].rows[-1][4] or 0)) + 2, 10) * A + 17 * A - if len(bl[a].out) == 2 and st["blocks"].get(a, {}).get("count") - and not st["blocks"].get(a, {}).get("cur") else 0) - widths = {a: 520 if fold(a) else max(block_w(bl[a], base, notes_w if st["blocks"].get(a, {}).get("notes") else 0), - split_w(a)) for a in order} - heights = {a: TAG + (ROW if fold(a) else len(fold_rows(bl[a].rows, st["blocks"].get(a, {}).get("cur"))) * ROW) + PAD - for a in order} - arches = [(idx[t], idx[a], (a, t)) for a, t in back] - dips = [(idx[a], idx[t], (a, t)) for a in order for t, _ in bl[a].out - if (a, t) not in back and idx[t] > idx[a] + 1] - al, dl = spans_levels(arches), spans_levels(dips) - cx0 = x + 24 + 48 * max(al.values(), default=0) + 12 - ys, yy = {}, y + TAG + 8 - for a in order: - ys[a] = yy - yy += heights[a] + 10 - yy += 10 # room under the last card for the way out's bar - hook = lambda a: max([28 + len(r[5]) * A for r in bl[a].rows if r[2] == "call" and r[5]] + [0]) if not fold(a) else 0 - chan = max(cx0 + widths[a] + hook(a) for a in order) + 24 - hgt = yy - y - C.tag(g, x, y, w, hgt, title, focus=True, note=note) - R, spine = 16, cx0 + 40 - paths = {} - for a in order: - for t, kind in bl[a].out: - e = (a, t) - ya, yt = ys[a] + heights[a] - 14, ys[t] + 12 - if e in back: - L = cx0 - 48 * al[e] - p = (Path(cx0, ya).to(L + R, ya).arc(L, ya - R, R, True).to(L, yt + R).arc(L + R, yt, R, True) - .to(cx0, yt)) - elif idx[t] == idx[a] + 1: - p = Path(spine, ys[a] + heights[a]).to(spine, ys[t]) - else: - Cx = chan + 32 * (dl[e] - 1) - p = (Path(cx0 + widths[a], ya).to(Cx - R, ya).arc(Cx, ya + R, R, True).to(Cx, yt - R) - .arc(Cx - R, yt, R, True).to(cx0 + widths[t], yt)) - paths[e] = p - for e, p in sorted(paths.items(), key=lambda kv: kv[0] in st.get("edge_trail", ())): - ink, sw, dash = edge_ink(e, st) - draw_path(g, p, ink, sw, dash, hl=10, hw=10) - counts = st.get("edge_counts", {}) - for a, t in back: # the turns, in the lobe - e = (a, t) - n = counts.get(e, 0) - if n: - L = cx0 - 48 * al[e] - g.t(L + 24, (ys[t] + ys[a] + heights[a]) / 2 + 7, "×%d" % n, S, DIM, MONO, "middle") - ats = {} - for a in order: - s0 = dict(st["blocks"].get(a, {})) - if len(bl[a].out) == 2 and not fold(a) and s0.get("count"): # a conditional reached: its two ways counted - (t1, k1), (t2, k2) = bl[a].out - tk, nt = (t1, t2) if k1 == "taken" else (t2, t1) - s0["split"] = (counts.get((a, tk), 0), counts.get((a, nt), 0)) - _, at = draw_block(g, cx0, ys[a], widths[a], bl[a], base, s0) - ats.update(at) - return hgt, ats, paths - - -# ---- rings: the comparison sheet's third form, each loop a circle its blocks sit on ---------------------------- -RING_AT = {0x12: ("o", 180), 0x1e: ("o", 235), 0x24: ("o", 300), 0x5d: ("o", 25), 0x97: ("o", 80), 0x99: ("o", 130), - 0x2f: ("i", 15), 0x56: ("i", 95), 0x5f: ("i", 185)} - - -def rings(g, x, y, w, h, st, title): - """sort as rings: the outer loop a circle of 170, its blocks round it clockwise; the inner loop a circle of 92 - inside it, touching it at its header; the way in and the way out as short tracks at the left; a loop's exit a - chord between the rings. Every edge an arc of its ring or a straight chord.""" - C.tag(g, x, y, w, h, title, focus=True, note="its blocks · the visits · the path · the loops' turns") - R, r = 170, 92 - ox, oy = x + w / 2 + 120, y + TAG + 24 + R - t0 = math.radians(300) - ix, iy = ox + (R - r) * math.cos(t0), oy + (R - r) * math.sin(t0) - ring = {"o": (ox, oy, R), "i": (ix, iy, r)} + C.tag(g, x, y, w, h, title, focus=True, note="its blocks · the visits so far · the path") + edges(g, bl, lay, back, pos, widths, heights, lh, ly, 12, st, base, x + 24, + max(pos[a][0] + widths[a] for a in bl) + 20, small=True, radius=12) + for a in bl: + draw_pill(g, *pos[a], bl, a, base, st, widths[a]) + return pos, max(by for _, by in pos.values()) + 24 - y + + +def fold_not_yet(bl, reached, groups): + """The blocks the run has not reached by the moment shown, folded: each group (the code beyond one way the run + has not taken yet, as far as it leads, cut so that no fold leads back into another) one dashed pill in the + place of its first block; an edge into or out of a member is the fold's.""" + out = {a: bl[a] for a in bl if a in reached or not any(a in ms for ms in groups)} + rep = {} + for ms in groups: + fb = Block("+%x" % ms[0], [r for m in ms for r in bl[m].rows]) + fb.folded = ms + out[ms[0]] = fb + rep.update({m: ms[0] for m in ms}) + for a, blk in list(out.items()): + seen = [] + for t, k in (blk.out if not hasattr(blk, "folded") else [o for m in blk.folded for o in bl[m].out]): + t2 = rep.get(t, t) + if t2 != a and t2 in out and t2 not in [s_ for s_, _ in seen]: + seen.append((t2, k)) + blk.out = seen + if hasattr(blk, "folded"): + blk.ret = False + return out + + +# ---- the first form: rings ---------------------------------------------------------------------------------- +def rings(g, x, y, w, h, bl, base, st, spec, title, moving=None, struck=None, tag=True): + """`rings`: each loop a circle its blocks sit on, upright, clockwise from its header at the ring's left (9 + o'clock), where the way in arrives; an inner loop a smaller ring outside its parent, touching it at its header, + which is the parent's block at 3 o'clock. An edge from a block to the next on its ring, and a loop's back edge, + are arcs of the ring; an edge inside a loop that passes blocks of it is an arc 30 inside the ring; a way out + leaves along the ring's tangent, out of the pill's foot, and every bend after is a quarter circle of 16. + Outside every loop the blocks lie as `layers` lays them. The loop's turns so far at its centre. + spec: rings {name: (dx, dy, r)} from the origin; at {offset: (ring, degrees)}; free {offset: (dx, dy)}; + the origin (dx, dy) from the panel's corner; edges {(from, to): kind}, kind "line", ("arc", ring), + ("skip", ring) or a function of the places giving a Path; hook {offset: (dx, side)}.""" + if tag: + C.tag(g, x, y, w, h, title, focus=True, note="its blocks · the visits so far · the path · the loops' turns") + ox, oy = x + spec["origin"][0], y + spec["origin"][1] + ring = {k: (ox + dx, oy + dy, r) for k, (dx, dy, r) in spec["rings"].items()} pos = {} - for off, (k, deg) in RING_AT.items(): - cx, cy, rr = ring[k] - pos[O(off)] = (cx + rr * math.cos(math.radians(deg)), cy + rr * math.sin(math.radians(deg))) - pos[O(0x0)] = (ox - R - 170, oy) - pos[O(0xa7)] = (ox - R - 170, oy + 96) - texts = {a: ("+%x" % (a - SORT_BASE), "×%d" % st["blocks"][a]["count"] if st["blocks"][a]["count"] else "") - for a in SORT_BL} - pw = {a: 24 + (len(texts[a][0]) + len(texts[a][1]) + 1) * A + 8 for a in SORT_BL} + for off, (k, deg) in spec["at"].items(): + cx, cy, r = ring[k] + pos[base + off] = (cx + r * math.cos(math.radians(deg)), cy + r * math.sin(math.radians(deg))) + for off, (dx, dy) in spec["free"].items(): + pos[base + off] = (ox + dx, oy + dy) + pw = {a: pill_w(bl, a, base, st) for a in pos} inside = lambda a, px, py: abs(px - pos[a][0]) < pw[a] / 2 + 4 and abs(py - pos[a][1]) < 16 - def on_ring(a, t, k): - """The arc of ring k from a's pill to t's, clockwise, cut where each pill ends.""" - cx, cy, rr = ring[k] + def arc(a, t, k, inset=0): + cx, cy, r = ring[k] + r -= inset a0 = math.atan2(pos[a][1] - cy, pos[a][0] - cx) a1 = math.atan2(pos[t][1] - cy, pos[t][0] - cx) while a1 <= a0: a1 += 2 * math.pi - pt = lambda th: (cx + rr * math.cos(th), cy + rr * math.sin(th)) + pt = lambda th: (cx + r * math.cos(th), cy + r * math.sin(th)) s, e = a0, a1 while inside(a, *pt(s)): - s += 0.005 + s += 0.004 while inside(t, *pt(e)): - e -= 0.005 + e -= 0.004 p = Path(*pt(s)) - p.arc(*pt(e), rr, True) + steps = max(1, int((e - s) / (math.pi / 2)) + 1) # an arc a quarter or less at a time + for k_ in range(1, steps + 1): + p.arc(*pt(s + (e - s) * k_ / steps), r, True) return p paths = {} - for a in SORT_BL: - for t, kind in SORT_BL[a].out: - ka, kt = RING_AT.get(a - SORT_BASE, (None,))[0], RING_AT.get(t - SORT_BASE, (None,))[0] - if (a, t) == (O(0x0), O(0x12)): - p = Path(pos[a][0] + pw[a] / 2, oy).to(pos[t][0] - pw[t] / 2, oy) - elif (a, t) == (O(0x12), O(0xa7)): - sx = pos[a][0] - 20 - p = (Path(sx, oy + 12).to(sx, oy + 40).arc(sx - 56, oy + 96, 56, True) - .to(pos[t][0] + pw[t] / 2, oy + 96)) - elif ka and kt and ka == kt or (a - SORT_BASE, t - SORT_BASE) in ((0x24, 0x2f), (0x5f, 0x24)): - p = on_ring(a, t, "i" if (a - SORT_BASE, t - SORT_BASE) in ((0x24, 0x2f), (0x5f, 0x24)) else ka) - else: # between the rings, or across one: a chord - (ax, ay), (tx, ty) = pos[a], pos[t] - d = math.hypot(tx - ax, ty - ay) - ux, uy = (tx - ax) / d, (ty - ay) / d - s, e = 0, d - while inside(a, ax + ux * s, ay + uy * s): - s += 1 - while inside(t, ax + ux * e, ay + uy * e): - e -= 1 - p = Path(ax + ux * s, ay + uy * s).to(ax + ux * e, ay + uy * e) - paths[(a, t)] = p + for (fo, to), kind in spec["edges"].items(): + a, t = base + fo, base + to + if callable(kind): + p = kind(pos, pw, base) + elif kind == "line": + p = Path(pos[a][0] + pw[a] / 2, pos[a][1]).to(pos[t][0] - pw[t] / 2, pos[t][1]) + elif kind[0] == "arc": + p = arc(a, t, kind[1]) + else: + p = arc(a, t, kind[1], 30) + paths[(a, t)] = p for e, p in sorted(paths.items(), key=lambda kv: kv[0] in st.get("edge_trail", ())): ink, sw, dash = edge_ink(e, st) - if len(p.pts) > 2: # an arc: its head on the tangent at its end - draw_arc_head(g, p, ink, sw, dash) - else: - draw_path(g, p, ink, sw, dash) - for (cx, cy, rr), e in ((ring["o"], (O(0x99), O(0x12))), (ring["i"], (O(0x5f), O(0x24)))): - n = st["edge_counts"].get(e, 0) - tx, ty = (cx, cy) if rr < R else (cx - 80, cy + 60) - g.t(tx, ty + 7, "×%d" % n, S, DIM, MONO, "middle") - for a in SORT_BL: - s0 = st["blocks"][a] - n, cur = s0.get("count", 0), s0.get("cur") - px, py = pos[a][0] - pw[a] / 2, pos[a][1] - 12 - pill(g, px, py, pw[a], RAISED if n else PAGE, GOLD if cur else RULE, 3 if cur else 2) - g.t(px + 12, b(py), texts[a][0], S, VELLUM if n else FAINT, MONO) - if texts[a][1]: - g.t(px + pw[a] - 12, b(py), texts[a][1], S, DIM, MONO, "end") - sx, sy = pos[O(0x5f)][0] + 26, pos[O(0x5f)][1] - 12 - g.path(f"M{sx:.1f},{sy:.1f} v-6 a5,5 0 0 1 10,0 v6", DIM, 2) - g.t(sx + 16, sy - 6, "swap", S, VELLUM, MONO) + (draw_arc_head if len(p.pts) > 2 and abs(p.pts[-1][0] - p.pts[-2][0]) > 0.5 and + abs(p.pts[-1][1] - p.pts[-2][1]) > 0.5 else draw_path)(g, p, ink, sw, dash) + for k, e in spec["turns"].items(): # each loop's turns so far, at its centre, under the line its pills are on + cx, cy, _ = ring[k] + cy += spec.get("turns_dy", 30) + e = (base + e[0], base + e[1]) + n = st.get("edge_counts", {}).get(e, 0) + if not n: + continue + s, word = str(n), " turn" if n == 1 else " turns" + x0 = cx - (len(s) * A + gen.tw(word, 18, "sans")) / 2 + if struck == e: + g.rect(x0 - 5, cy - 11, len(s) * A + 10, 22, C.SOFT) + g.t(x0, cy + 7, s, S, BRIGHT if struck == e else VELLUM, BOLD if struck == e else MONO) + g.t(x0 + len(s) * A, cy + 6, word, 18, DIM, "sans") + for a in pos: + s0 = dict(st["blocks"].get(a, {})) + if moving: + s0.pop("cur", None) + draw_pill(g, pos[a][0] - pw[a] / 2, pos[a][1] - 12, bl, a, base, {"blocks": {a: s0}}, pw[a]) + if moving: + mark(g, paths[moving[0]], moving[1]) + return paths, pos def draw_arc_head(g, p, ink, sw, dash): @@ -904,72 +488,271 @@ def draw_arc_head(g, p, ink, sw, dash): gen.head_tri(g, x2, y2, (x2 - x1) / l_, (y2 - y1) / l_, ink, 8, 8) -def frame_forms(name): - """Mock 43: sort's graph four ways, at the same moment and at the lens's scale: the present form, its layers - rounded, rings, and the track (recommended), each in the box it is given and at the size it needs.""" - gen.W, gen.H = 1920, 1600 +# ---- the data: sort as the scene builds it ------------------------------------------------------------------ +SORTC = [r for r in read_dis("sort-clang.dis") if 0x401150 <= r[0] < 0x401200] +SORT_BASE = 0x401150 +SORT_BL = blocks(SORTC, SORT_BASE) +SB = sorted(SORT_BL) +# the block leaders the run hit, from sort's entry to its return: ztrace record --by insn --from sort, clang -O0 +SORT_PATH = [SORT_BASE + int(o, 16) for o in ( + "0 12 1e 24 2f 56 5d 97 99 12 1e 24 2f 56 5d 97 99 12 1e 24 2f 56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5f 24 2f " + "56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5f 24 2f 56 5f 24 2f 56 5f 24 2f 56 " + "5f 24 2f 56 5d 97 99 12 1e 24 2f 56 5f 24 2f 56 5f 24 2f 56 5d 97 99 12 a7").split()] +O = lambda off: SORT_BASE + off + + +def sort_state(upto, cur, trail_rows, notes=None, cur_line=12): + """The run's facts by the moment shown: the path's first `upto` blocks, and nothing after.""" + cnt, ec, trail = run_state(SORT_BL, SORT_PATH, upto, SORT_BASE) + blk = {a: {"count": cnt.get(a, 0)} for a in SORT_BL} + if cur: + ca = max(a for a in SORT_BL if a <= cur) + blk[ca].update(cur=cur, trail=trail_rows, notes=notes or {}, cur_line=cur_line) + return {"blocks": blk, "edge_counts": ec, "edge_trail": trail} + + +# the 11th time through the compare: i = 6, j = 4, a[3] = 17 against a[4] = 5; the stop is the jne after it +# (sort-dbg.txt). Five swaps so far, five turns of each loop; the function's way out not taken yet. +UPTO = [i for i, a in enumerate(SORT_PATH) if a == O(0x56)][10] + 1 +PC = 0x4011ab +TRAIL_ROWS = [0x4011a9, 0x4011a6, 0x4011a3] +NOTES = {0x4011a6: [("7fffffffecd3 ", STACK), ("◂ ", FAINT), ("1", VELLUM)], + 0x4011a9: [("1", VELLUM), (" : ", FAINT), ("1", VELLUM), (" ", FAINT), ("zf", DIM)], + 0x4011ab: [("taken", VELLUM), (" · reads zf", FAINT)]} + + +def down_round(sx, sy, ty, tx, ey, r=16): + """A way out: straight down from (sx, sy) to ty, round a quarter, across to tx, round a quarter, and straight + to (tx, ey), up or down.""" + left = tx < sx + p = Path(sx, sy).to(sx, ty - r) + p.arc(sx + (-r if left else r), ty, r, left) + up = ey < ty + p.to(tx + (r if left else -r), ty) + p.arc(tx, ty + (-r if up else r), r, left if up else not left) + return p.to(tx, ey) + + +SORT_RINGS = { + "origin": (434, TAG + 14 + 144), + "rings": {"o": (0, 0, 140), "i": (224, 0, 84)}, + "at": {0x12: ("o", 180), 0x1e: ("o", 225), 0x24: ("o", 0), 0x5d: ("o", 60), 0x97: ("o", 110), 0x99: ("o", 145), + 0x2f: ("i", 270), 0x56: ("i", 0), 0x5f: ("i", 75)}, + "free": {0x0: (-320, 0), 0xa7: (-180, 124)}, + "edges": {(0x0, 0x12): "line", (0x12, 0x1e): ("arc", "o"), (0x1e, 0x24): ("arc", "o"), (0x24, 0x2f): ("arc", "i"), + (0x2f, 0x56): ("arc", "i"), (0x56, 0x5f): ("arc", "i"), (0x5f, 0x24): ("arc", "i"), + (0x24, 0x56): ("skip", "i"), (0x5d, 0x97): ("arc", "o"), (0x97, 0x99): ("arc", "o"), + (0x99, 0x12): ("arc", "o"), + # the inner loop's way out: down out of +56's foot, along its ring's tangent, under +5f, into +5d's end + (0x56, 0x5d): lambda pos, pw, base: (Path(pos[base + 0x56][0] + 30, pos[base + 0x56][1] + 12) + .to(pos[base + 0x56][0] + 30, pos[base + 0x5d][1] - 16) + .arc(pos[base + 0x56][0] + 14, pos[base + 0x5d][1], 16, True) + .to(pos[base + 0x5d][0] + pw[base + 0x5d] / 2, pos[base + 0x5d][1])), + # the function's way out: down out of +12's foot, outside the ring, into +a7 + (0x12, 0xa7): lambda pos, pw, base: Path(pos[base + 0x12][0] - 40, pos[base + 0x12][1] + 12) + .to(pos[base + 0xa7][0], pos[base + 0xa7][1] - 12)}, + "turns": {"o": (0x99, 0x12), "i": (0x5f, 0x24)}, +} + + +# ---- libc's open, at its syscall: a tree of branches, what is not reached yet folded -------------------------- +OPEN = read_dis("libc-open.dis", lines=False) +OPEN_BASE = 0x110ec0 +L = 0x7ffff7c00000 + + +def rebase(rows): + return [(a + L, ln, mn, ops, (t + L) if t else None, callee) for a, ln, mn, ops, t, callee in rows] + + +OPEN_BL = blocks(rebase(OPEN), OPEN_BASE + L) +OPEN_PATH = [a + L for a in (0x110ec0, 0x110ee9, 0x110efb, 0x110fb0)] # by the syscall (mock 16's moment 4) + + +# ---- reverse: a loop's turn ------------------------------------------------------------------------------------ +REV = read_dis("reverse-O0.dis") +REV_BASE = 0x401188 +REV_BL = blocks(REV, REV_BASE) +RB = sorted(REV_BL) +R0, R1, R2, R3 = RB +REV_PATH = [R0, R2, R1, R2, R1, R2, R1, R2, R3] +REV_RINGS = { + "origin": (441, TAG + 14 + 82), + "rings": {"o": (0, 0, 70)}, + "at": {R2 - REV_BASE: ("o", 180), R1 - REV_BASE: ("o", 0)}, + "free": {R0 - REV_BASE: (-230, 0), R3 - REV_BASE: (-100, 100)}, + "edges": {(R0 - REV_BASE, R2 - REV_BASE): "line", (R2 - REV_BASE, R1 - REV_BASE): ("arc", "o"), + (R1 - REV_BASE, R2 - REV_BASE): ("arc", "o"), + (R2 - REV_BASE, R3 - REV_BASE): lambda pos, pw, base: Path(pos[R2][0] - 30, pos[R2][1] + 12) + .to(pos[R3][0], pos[R3][1] - 12)}, + "turns": {"o": (R1 - REV_BASE, R2 - REV_BASE)}, +} + + +# ---- the disassembly beside the graph, linear, its blocks ruled --------------------------------------------------- +TEXT = read_dis("sort-clang.dis") # the program's text: swap, sort, main +FUNC = lambda a: "swap" if a < 0x401150 else "sort" if a < 0x401200 else "main" + + +def sort_disasm(g, y, n, line=12): + """n rows round the pc; each block's first row under a rule, its visits so far ranged right in the annotation's + room; the trail's three rows and the pc's with what they did; another function's rows `outside`.""" + i = [r[0] for r in TEXT].index(PC) + lo = max(0, min(i - n // 2, len(TEXT) - n)) + st = sort_state(UPTO, PC, TRAIL_ROWS) + notes = dict(NOTES) + notes[0x4011a3] = [("7fffffffecd3 ", STACK), ("◂ ", FAINT), ("1", VELLUM)] + rows, last = [], None + for a, ln, mn, ops, t, callee in TEXT[lo:lo + n]: + f = FUNC(a) + state = "cur" if a == PC else {0x4011a9: "trail0", 0x4011a6: "trail1", 0x4011a3: "trail2"}.get(a) + note = ("runs", notes[a]) if a in notes else ("text", callee, VELLUM) if mn == "call" else None + if f != "sort": + state = "other_first" if f != last else "other" + note = ("text", f, DIM) if f != last else note + rows.append((a, ln if f == "sort" else None, mn, + [(t, CODE)] if t and (mn.startswith("j") or mn == "call") else [(ops, VELLUM)], state, note)) + last = f + at = C.disasm(g, y, rows, "sort", line) + for a in at: + if a in SORT_BL: # a block's first row: the rule over it, its pill's count in digits + yy = at[a] + g.rect(C.LX + 2, yy, C.CW - 4, 2, RULE) + n_ = st["blocks"][a]["count"] + if n_: + g.t(C.LX + C.CW - 12, b(yy), "×%d" % n_, S, FAINT, MONO, "end") + line12 = [at[r[0]] for r in rows if r[1] == 12 and r[0] < 0x4011af] + return at, (min(line12), max(line12) + ROW), lo + + +# ---- the mocks ------------------------------------------------------------------------------------------------ +def frame_sort_map(name): + """Mock 22: the map's first two columns at the 11th compare: the drawing (rings, at its size in the frame) over + the source whole, and the disassembly column linear, 69 rows round the pc, each block ruled with its visits so + far; the thread across the gutter; the working frame's windows outlined.""" + gen.W, gen.H = 2000, 1860 g = Svg() st = sort_state(UPTO, PC, TRAIL_ROWS, NOTES) - g.t(64, 56, "sort's graph, four ways", 36, BRIGHT, "sansm") - g.t(64, 90, "The same moment in each (the 11th compare: 17 > 5, jne about to take the swap); the lens's scale, " - "mono 20. Veiled: what falls outside the box the frame gives the lens.", 20, DIM, "sans") + g.t(112, 60, "the map: sort's rings over the source, the disassembly linear beside them, at the 11th compare", 22, + DIM, "sans") + rings(g, 112, 96, 880, 344, SORT_BL, SORT_BASE, st, SORT_RINGS, "the blocks of sort") + src = open(HERE + "/../../anim/tools/sort.c").read().split("\n") + C.LX = 112 + ys = C.source(g, 452, 22, src, 1, 12, [14, 13], "sort.c", 22) + C.LX = 1024 + at, run, lo = sort_disasm(g, 96, 69) + C.LX = 64 + D.thread_across(g, ys, [run]) + g.frame(112 - 4, 96 - 4, 888, 352, DIM, 2) # the frame's windows (25): the drawing whole + for bx, by, bw, bh in ((112, 452 + TAG + PAD + 8 * ROW, 880, 6 * ROW), (1024, at[0x4011ab] - 5 * ROW, 880, 11 * ROW)): + g.frame(bx - 1, by - 1, bw + 2, bh + 2, DIM, 2) # on the rows' edges, never through a line's letters + g.rect(112, 1798, 1792, 2, RULE) + g.t(112, 1824, "the map's stage ends at 1784; the other columns (memory, the registers whole, the stack) as in 19", + 18, FAINT, "sans") + g.save(name) + + +def frame_strip(name): + """Mock 24: reverse's loop as a ring, four instants: the condition; the edge taken, the mark on the ring's top; + the turn, the mark coming round under it, the count at the centre struck; the way out, down the tangent.""" + gen.W, gen.H = 1920, 712 + g = Svg() + inst = [ + ("1", "the condition", "the pc on jne in the test's block, the second time; its two ways out", 4, 0x4011ce, None), + ("2", "the edge taken", "taken: round the top of the ring to the body, the mark on it", 4, None, + ((R2, R1), 0.5)), + ("3", "the loop's turn", "back round the foot of the ring to the test; the count at its centre struck as it lands", + 5, None, ((R1, R2), 0.5)), + ("4", "the way out", "not taken, the fourth time: down the tangent, out of the ring, landed", 9, 0x4011d0, None), + ] + for k, (num, title, sub, upto, cur, moving) in enumerate(inst): + x, y = 64 + (k % 2) * 912, 40 + (k // 2) * 320 + g.t(x, y + 24, num, 28, GOLD, "sansb") + g.t(x + 28, y + 24, title, 28, VELLUM, "sansm") + g.t(x, y + 52, sub, 18, FAINT, "sans") + path = REV_PATH[:upto] + ([moving[0][1]] if moving else []) + cnt, ec, trail = run_state(REV_BL, path, len(path), REV_BASE) + if moving: # the mark is on its edge: the target not yet entered, the edge lit + cnt[moving[0][1]] -= 1 + st = {"blocks": {a: {"count": cnt.get(a, 0)} for a in REV_BL}, "edge_counts": ec, "edge_trail": trail} + if cur: + ca = max(a for a in REV_BL if a <= cur) + st["blocks"][ca].update(cur=cur) + rings(g, x, y + 72, 880, 248, REV_BL, REV_BASE, st, REV_RINGS, "the blocks of reverse", moving=moving, + struck=moving[0] if moving and moving[0] == (R1, R2) else None) + g.save(name) - def veil(x, y, w, h): - g.o.append(f'') + +def frame_forms(name): + """Mock 43: the graph's two forms at the lens's scale, every count as of the moment shown: rings (the first), on + sort in the pane the frame gives it; layers (the second), on sort, and on libc's open at its syscall, a tree of + branches, what the run has not reached yet folded.""" + gen.W, gen.H = 1920, 1260 + g = Svg() + st = sort_state(UPTO, PC, TRAIL_ROWS, NOTES) + g.t(64, 56, "the graph's two forms", 36, BRIGHT, "sansm") + g.t(64, 90, "At the lens's scale, mono 20; each in the pane the `blocks` split gives it, 880 by 344. Every number is " + "the run's by the moment shown; veiled: what a pane must pan to.", 20, DIM, "sans") def label(x, y, key, title, sub): - g.t(x, y, key, 28, GOLD if key == "4" else BRIGHT, "sansb") + g.t(x, y, key, 28, GOLD if key == "1" else BRIGHT, "sansb") g.t(x + 30, y, title, 28, VELLUM, "sansm") g.t(x, y + 28, sub, 18, FAINT, "sans") + + def veil(x, y, w, h): + g.o.append(f'') + label(64, 152, "1", "rings: sort at the 11th compare", "each loop a ring, the inner touching the outer at its " + "header; ways out down the tangent; whole in 880 by 344") + rings(g, 64, 212, 880, 344, SORT_BL, SORT_BASE, st, SORT_RINGS, "the blocks of sort") cols = {a: 0 for a in SORT_BL} cols[O(0xa7)] = 1 cols[O(0x5f)] = 1 - for k, (key, title, sub, rounded) in enumerate(( - ("1", "present: layers, boxes, square lanes", "ten layers, 400 high: past the lens's 296 (veiled), so it " - "pans; a third of its width", False), - ("2", "the same layers, rounded", "pills and round corners: smoother, and just as tall", True))): - x = 64 + k * 912 - label(x, 152, key, title, sub) - _, hh = silhouette(Svg(), x, 212, 880, 999, SORT_BL, SB[0], SORT_BASE, cols, st, "", rounded, pitch=330) - silhouette(g, x, 212, 880, hh + 16, SORT_BL, SB[0], SORT_BASE, cols, st, "the blocks of sort", rounded, pitch=330) - veil(x - 2, 212 + 296, 884, hh + 16 - 296 + 2) - label(64, 704, "3", "rings", "each loop a circle its blocks sit on, the inner inside the outer: 420 high, " - "past the band's 200 (veiled)") - rings(g, 64, 764, 880, 420, st, "the blocks of sort") - veil(62, 764 + 200, 884, 222) + label(976, 152, "2", "layers: the same moment", "the loops as lanes; 400 high, so it pans in 344 (veiled): " + "for loops, rings") + _, hh = layered(Svg(), 976, 212, 880, 999, SORT_BL, SB[0], SORT_BASE, cols, st, "", pitch=330) + layered(g, 976, 212, 880, hh + 16, SORT_BL, SB[0], SORT_BASE, cols, st, "the blocks of sort", pitch=330) + veil(974, 212 + 344, 884, hh + 16 - 344 + 2) + # libc's open at its syscall: the branches it has taken, and a fold for each run of what it has not reached yet + o = lambda off: OPEN_BASE + L + off + bl = fold_not_yet(OPEN_BL, set(OPEN_PATH), [[o(x) for x in (0x5b, 0x63, 0x6b, 0xad, 0xb9, 0x136, 0x149)], + [o(x) for x in (0xbe, 0x10a, 0x112, 0x114, 0x123, 0x128, 0x12c, 0x130)]]) + ost = {"blocks": {a: {"count": 1 if a in OPEN_PATH else 0} for a in bl}, + "edge_counts": Counter(zip(OPEN_PATH, OPEN_PATH[1:])), + "edge_trail": list(reversed(list(zip(OPEN_PATH, OPEN_PATH[1:]))))} + ost["blocks"][OPEN_PATH[-1]]["cur"] = True + ocols = {a: (0 if a in OPEN_PATH else 1) for a in bl} + label(64, 670, "2", "layers: libc's open at its syscall", "a tree of branches and no loop (rings has none to " + "draw, and is this); what is not reached yet folded, dashed") + layered(g, 64, 730, 880, 344, bl, OPEN_PATH[0], OPEN_BASE + L, ocols, ost, "the blocks of open · libc.so.6", + pitch=380) nx = 976 for i, (s, ink) in enumerate(( - ("What each costs", VELLUM), - ("1 The tools' picture. Tall by nature: a layer a block,", DIM), - (" so it pans in a short pane, and leaves the width.", DIM), - ("2 Rounding the corners does not change the shape.", DIM), - ("3 The most circular, and a loop is a ring; but rings", DIM), - (" want a square pane, a loop's way out is a chord", DIM), - (" across them, and pills on its sides sit across it.", DIM), - ("4 The track. A line of blocks as they run, each loop", VELLUM), - (" an arch over its own blocks: a closed shape, its", VELLUM), - (" turns at its centre; a jump past blocks a dip", VELLUM), - (" under them. Wide and short: 11 blocks in 1622", VELLUM), - (" by 150, whole. Its order is the disassembly's,", VELLUM), - (" which is under the source; run down, it is the", VELLUM), - (" map's column with its rows.", VELLUM))): - g.t(nx, 730 + i * 30, s, 22 if i == 0 else 20, ink, "sansm" if i == 0 else "sans") - label(64, 1220, "4", "the track: recommended", "the band across the frame, 1792 by 200: the whole graph, no pan") - paths, y0, xs, pw = track_lens(g, 64, 1280, 1792, 200, SORT_BL, SB[0], SORT_BASE, st, "the blocks of sort") - print("43: the track is %d wide" % (max(xs[a] + pw[a] for a in xs) - min(xs.values()))) - g.t(64, 1530, "Ink in 3 and 4: never taken in the whole run, dashed rule (j > 0 failing); not yet, rule (the " - "way out); taken, dim; the last three, the trail's golds. 1 and 2 keep the layers' ink: never taken, rule.", - 18, DIM, "sans") + ("Which, and why", VELLUM), + ("1 Rings, the first form. A loop is a ring and the mark going", VELLUM), + (" round it is the picture of iteration; its turns at its", VELLUM), + (" centre. Nested loops: rings touching at the header.", VELLUM), + ("2 Layers, the second, for a function of branches: the path", DIM), + (" reads down, and a fork is two columns. Rings with no", DIM), + (" loop is this. For loops it is tall and pans.", DIM), + (" The track is withdrawn: a ring says a loop, a layer a", DIM), + (" branch; a line of blocks said neither, and its arches", DIM), + (" were rings flattened to fit a band.", DIM), + ("Nothing from after the moment: counts so far; an edge or", VELLUM), + ("a block not reached yet is quiet (rule, page, no count);", VELLUM), + ("open's folds are what it has not reached yet, and open", VELLUM), + ("as the run gets there.", VELLUM))): + g.t(nx, 690 + i * 30, s, 22 if i == 0 else 20, ink, "sansm" if i == 0 else "sans") + g.t(64, 1120, "Ink: not reached so far, rule; taken so far, dim; the last three, the trail's golds, the newest 3. " + "A fold, dashed. No count before a block's first visit.", 18, DIM, "sans") g.save(name) if __name__ == "__main__": assert len(SORT_BL) == 11 and len(REV_BL) == 4, (len(SORT_BL), len(REV_BL)) assert Counter(SORT_PATH)[O(0x56)] == 17 and Counter(SORT_PATH)[O(0x5f)] == 10 - lay_, back_, loops_ = loops_of(SORT_BL, SB[0]) - assert [a - SORT_BASE for a in track_order(SORT_BL, lay_, loops_)] == \ - [0x0, 0x12, 0x1e, 0x24, 0x2f, 0x56, 0x5f, 0x5d, 0x97, 0x99, 0xa7] + st_ = sort_state(UPTO, PC, TRAIL_ROWS) # nothing from after the moment: the way out not taken yet + assert st_["blocks"][O(0xa7)]["count"] == 0 and st_["edge_counts"][(O(0x12), O(0xa7))] == 0 + assert st_["blocks"][O(0x5f)]["count"] == 5 and st_["edge_counts"][(O(0x99), O(0x12))] == 5 frame_sort_map("22-graph-sort") - frame_open_map("23-graph-open") frame_strip("24-graph-strip") frame_forms("43-graph-forms") diff --git a/design/motion.md b/design/motion.md index 6e68c29..2e127b9 100644 --- a/design/motion.md +++ b/design/motion.md @@ -631,53 +631,54 @@ target is in the same region but out of the window. ### A block left -On a function's graph, the track ([`graph`](README.md#graph); mock 24 is +On a function's graph, in `rings` ([`graph`](README.md#graph); mock 24 is reverse's loop, 25 sort in the frame): in sort, `jne` decides between the swap and the inner loop's way out. The cause is in the disassembly under -the source; the decision is told in the band. +the source; the decision is told in the drawing over it. | Frames | | | --- | --- | | 0 to 12 | fire on the `jne` row under the source; the pc's pill's gold frame pulses with it | | 18 to 24 | the chips it reads (`zf`), on the `test` row above, framed as read: what decides | -| 24 to 42 | the edge it takes draws gold, 3 units, head first, `standard`: along the line from the pill's end (taken, to the swap's block, 40 units), or out of its foot into a dip (not taken: under the swap's block to `+5d`, 331 units) | -| 42 to 54 (60) | the mark travels the edge: the gold plaque, its point the way it goes, leaves the pill, `glide`, 12 f and 2 f a 100 units (42 f at most): 12 f along the line, 18 f through the dip; the pill it left cools to the trail; the disassembly's plaque moves with the advance as ever | +| 24 to 42 | the edge it takes draws gold, 3 units, head first, `standard`: round the inner ring to the swap's block (taken, 58 units), or out of the pill's foot down the ring's tangent and under it to `+5d` (not taken: the inner loop's way out, 318 units) | +| 42 to 54 (60) | the mark travels the edge: the gold plaque, its point the way it goes, leaves the pill, `glide`, 12 f and 2 f a 100 units, 12 f at least, 42 f at most: 12 f round the ring, 18 f down the way out; the pill it left cools to the trail; the disassembly's plaque moves with the advance as ever | | 54 (60) | it lands on the target's pill: the advance | | 48 to 60, 60 | arm, strike: the target's count, `×5` to `×6` | | 54 to 72 | the oldest of the three trail edges cools to `dim` | -| 72 to 96 | rest: 1.6 s (1.7 through the dip, every time after the landing 6 f later) | - -**A loop's turn** is the same over the arch: up out of the latch's top, -back over the loop's own blocks, down into the header's top; the one -thing that goes back. The mark keeps its speed: sort's inner arch in the -lens is 672 units, 26 f; the outer 1433, 40 f (on the map, 966 and 1516, -the cap: 42 f). The loop's count at its centre, under the arch, is armed -as the mark comes over its top and struck as it lands, `×2` to `×3`: the -mark going round the loop's closed shape and the number in its middle -going up are one picture, the picture of iteration. - -**Rows into cards** (`spread`, and back, `gather`): a scene that shows -its disassembly as a track on the map, or a `dive` and a `surface` -between the map's track and the working frame's rows. The track's order -is the column's but where a loop keeps its blocks together, so what -persists barely moves: the column parts at each block's first row (24 f, -`glide`, the rows under each break gliding down to make the break and -the card's head, top down, 2 f apart), a block whose place on the line is -not its place in memory gliding to it over page on the same 24 f; then -the cards' frames and heads fade in round their rows (12 f) and the edges -draw, the line top down, then the lanes and the channels (2 f apart, 12 f -each). Backwards, the edges and frames go first and the rows close up -last. No text is ever over text: a row moves only over page. - -**At a run and a sprint** the track is at its best: a pass is a path, and -a loop is the mark going round. At a run the mark goes pill to pill in 8 -f (over an arch, 12), each edge it takes flashes gold and cools in 8 f, -the counts change in place; nothing is struck. At a sprint, on the map, -the gold moves only when the card changes (4 f at most), the three trail -edges follow it, the loops' counts tick in their lobes, and the picture -settles at the phrase's end: the counts are where the run left them, the -heat of the path in their numbers. In the lens (a sprint the scene keeps -in the working frame) the same, the source and the disassembly veiled. +| 72 to 96 | rest: 1.6 s (1.7 down the way out, every time after the landing 6 f later) | + +**A loop's turn** is the same round the ring: from the latch, round the +ring's foot, up into the header at 9 o'clock; the one thing that goes +back, and it goes back the way the ring turns. The mark keeps its speed +(sort's inner arc, 58 units, and outer, 50: 12 f each). The count at the +ring's centre is armed as the mark leaves the latch and struck as it +lands, `4 turns` to `5 turns`: the mark going round the circle and the +number in its middle going up are one picture, the picture of iteration. +The ring does not move; only the mark and the gold behind it do. + +**The first time** (`reach`): an edge the run has not taken before is +`rule` until the mark sets off along it, and draws in gold under the mark +as any taken edge does; its target, quiet until then (on the page, its +offset faint, no count), fills to `raised` as the mark lands (12 f), its +offset brightening, `×1` fading in (6 f) and struck. Nothing about a +block is shown before the run gets there. **A fold opening** (`unfold`): +as the mark sets off into a fold of blocks not reached yet, the pills +beyond it make room along the layout's own way, round the ring or down +the layers (24 f, `glide`), the dashed pill splits into its blocks, quiet, +in their places (12 f, 2 f apart in address order), and the mark lands +on the one reached (`reach`). A fold only opens; what a viewer has seen +placed stays where it was, or moves only along its ring or its column. + +**At a run and a sprint** the rings are at their best: a pass is a path, +and a loop is the mark going round. At a run the mark goes pill to pill +in 8 f, each edge it takes flashes gold and cools in 8 f, the counts +change in place; nothing is struck. At a sprint, on the map, the gold +moves only when the block changes (4 f at most), the three trail edges +follow it, the turns tick at the rings' centres, and the linear +disassembly's gold row moves with it; the picture settles at the phrase's +end: the counts are where the run left them, the heat of the path in +their numbers. In the frame (a sprint the scene keeps there) the same, +the source and the disassembly veiled. ### A pointer opened @@ -854,7 +855,7 @@ own path and its own scale. | 24 to 96 | each window travels to its panel's place, its scale from a half to whole on its logarithm, `glide`; the panels set off 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over the ones before, so that two crossing are seen to cross. With each, the same 72 f and the same stagger, the rest of its column (the map's panel it is a window on: the file, the 69 instructions, the stack from 16 words above rsp, the region's dump) squeezes into the pane's strip: from its place at half size to the strip's rect, its width and its height each on its logarithm (to 36 of 880; to 4 of 24 a row), its window's outline riding on it. The registers' and the drawing's windows are their panels whole and bring no column | | 24 to 72 | the map's parts no pane takes (the backtrace, the key, the memory round the pointers, a loupe's panel) fade where they are, veiled | | 24 to 96 | with the move, the registers fold: the map's panel has every register and every chain; as it lands each quiet register's row glides into its cell, three to a row, its chain past the first hop fading over the first 24 f, so the panel arrives at its height in the frame and the stack's window at its own, the longer one | -| 72 to 96 | the drawing crossfades from the map's size to the frame's within its box; the `blocks` lens's track, which is not a window of the map (the map's disassembly column is the track with its rows, and `gather`s into the pane's rows on its way), fades in across the band | +| 72 to 96 | the drawing crossfades from the map's size to the frame's within its box, where the two differ | | 84 to 102 | each squeezed column crossfades into its strip's strokes (12 f); the working frame's tags, rules and lanes fade in; the clock's count fades in (mock 20) | | 102 to 138 | still | @@ -881,12 +882,19 @@ What is played on the map, and why: In the working frame each pane's minimap is secondary action: its window glides with the pane's scroll (24 f); a mark the window does not show -`flash`es on its row in the strip once (12 f) as it is struck; a jump to a -row of the same column farther than the window's height shows there -first, the gold lighting on its new row and the window gliding to it (24 -f) before the pane fades through (12 out, 12 in), so the eye knows where -the pane went before it changes; and every change on a strip starts 6 f -after the primary onset it follows, never on that frame. A scene that opens on the map establishes it (0 to 48), its +`flash`es on its row in the strip once (12 f) as it is struck; and every +change on a strip starts 6 f after the primary onset it follows, never on +that frame. Between a pane and its whole column nothing cuts: + +| A pane | Frames | | +| --- | --- | --- | +| `unroll`: the whole column for a beat ("the whole function", "the whole stack") | 0 to 18 | the panes it will cover take the veil; the strip's window framed bright (6 f) | +| | 18 to 54 | the column grows out of the strip over the pane and the veiled panes under it, `glide`: from the strip's rect to as tall as the stage allows (the column's rows scaling from the strip's 4 units up, on the logarithm, to as many as fit: sort's text, 79 rows in 840, 10 a row; a 22-line file 24, readable), its strokes turning back into text as they pass 8 a row; the window's outline rides from the strip to its rows in the column, and the pane's own rows are the ones inside it, so nothing appears or vanishes | +| | 54 to (at least) 114 | held: the caption reads it, the pc's row gold, the marks of the moment on their rows | +| `roll` | 36 f | the reverse: the column shrinks back into the strip round the outline, which lands as the strip's window; the veil lifts (18 f) | +| a far jump in the same column, at a walk | 96 f | `unroll` (36); the window travels along the column to its new place (24, `glide`), the mark lighting gold at its new row as the window reaches it; `roll` there (36). The pane comes back at its new place without a fade | +| a far jump, at a run | 36 f | the new row lights on the strip, the strip's window glides to it (24), the pane fades through (12 out, 12 in): the strip has shown where it went | +| a `relayout` | 48 f | each strip grows or shrinks with its pane, its window with the pane's rows, on the same `glide` | A scene that opens on the map establishes it (0 to 48), its first caption at 60, dives at 150, and has its first step by 300 (5.0 s). ### Captions, opening, closing diff --git a/design/motion/motion.py b/design/motion/motion.py index 66571be..87823ff 100644 --- a/design/motion/motion.py +++ b/design/motion/motion.py @@ -47,11 +47,48 @@ REGIONS = { "boundary": (0, 528, W, 96), "kernel": (0, 624, W, 272), "caption": CAPTION}, "zoom": {"head": HEAD, "source": cols(0, 5, 0, 384), "registers": cols(0, 5, 408, 360), "stack": cols(5, 7, 0, 768), "caption": CAPTION}, - # The working frame (README.md, "The frame"): the two columns, the caption's text alone (not the clock's count - # at its right, which changes every step), the clock, the minimap. The default for any other name. - "frame": {"program": (64, 48, 880, 840), "state": (976, 48, 880, 840), "caption": (64, 906, 1400, 126), - "clock": (64, 894, 1600, 52), "minimap": (1664, 906, 192, 120)}, + # The working frame (README.md, "The frame"): the two columns, each less the strips of its panes' minimaps at + # its right (secondary action, their own regions), the caption's text alone (not the clock's count at its + # right, which changes every step), the clock. The default for any other name. + "frame": {"program": (64, 48, 838, 840), "program strips": (902, 48, 40, 840), "state": (976, 48, 838, 840), + "state strips": (1814, 48, 40, 840), "caption": (64, 906, 1400, 126), "clock": (64, 894, 1792, 52)}, } + + +# Each pane's minimap (README.md, "The map and the minimap"): a strip 40 wide inside its frame at its right, +# under the tag; the source, the disassembly, the stack and a dump (the band's view) have one. A pane's region +# stops at its strip, which is a region of its own, secondary action. +def strips(panes): + out = {} + for name, (x, y, w, h) in panes.items(): + if name in ("source", "disasm", "stack", "view"): + out[name] = (x, y, w - 42, h) + out[name + " strip"] = (x + w - 42, y + 24, 40, h - 26) + else: + out[name] = (x, y, w, h) + return out + + +def split(drawing, view, source, disasm, slots, backtrace=0): + """A split's panes (theme.layout.split): a panel of n rows is 32 + 24 n, 12 apart.""" + ph = lambda n: 32 + 24 * n + out = {"drawing": (64, 48, 880, drawing), "view": (976, 48, 880, view)} if drawing else {} + left, right = 48 + (drawing + 12 if drawing else 0), 48 + (view + 12 if view else 0) + out.update({"source": (64, left, 880, ph(source)), "disasm": (64, left + ph(source) + 12, 880, ph(disasm)), + "registers": (976, right, 880, ph(17)), "stack": (976, right + ph(17) + 12, 880, ph(slots))}) + if backtrace: + out["backtrace"] = (976, right + ph(17) + 12 + ph(slots) + 12, 880, ph(backtrace)) + return out + + +# The working frame by split, its strips apart (`--regions none|beside|subject|blocks`): `blocks` is the +# graph over the program column, the source alone (twenty lines), the disassembly its view, seven rows. +_words = {"caption": (64, 906, 1400, 126), "clock": (64, 894, 1792, 52)} +_blocks = {**split(296, 200, 10, 9, 6), "view": (976, 48, 880, 32 + 24 * 7), "source": (64, 356, 880, 32 + 24 * 20)} +del _blocks["disasm"] +for _name, _panes in {"none": split(0, 0, 14, 17, 8, 4), "beside": split(152, 152, 8, 17, 8), + "subject": split(296, 200, 10, 9, 6), "blocks": _blocks}.items(): + REGIONS[_name] = {**strips(_panes), **_words} PALETTE = ["#9aa6d9", "#e8c46a", "#6fd6e6", "#7fdc9a", "#d59cf5", "#ff6a4a", "#eee6d2", "#17a0b0"] @@ -187,7 +224,9 @@ def report(video, names, counts, soft, sizes, fps): return ev, "\n".join(lines) -WORDS = ("head", "caption", "clock", "minimap") # regions that are not panels +# Regions that are not panels: the words, and the panes' minimaps (secondary action). +WORDS = ("head", "caption", "clock", "minimap", "program strips", "state strips", + "source strip", "disasm strip", "stack strip", "view strip") # One-frame changes that are right, by name: each a test of (region, frame, pixels moved there) that says # whether the POP at that frame is one of its kind. They are counted apart, never silently dropped. -- cgit v1.3