diff options
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 189 |
1 files changed, 184 insertions, 5 deletions
diff --git a/design/README.md b/design/README.md index cd7a730..9bae30b 100644 --- a/design/README.md +++ b/design/README.md @@ -74,16 +74,17 @@ this table. | | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | 8 or 6 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, 8 or 10 lines | -| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows; a [`descent`](#descent): a window a call deep, the kernel at the floor | +| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows; a [`descent`](#descent): a window a call deep, the kernel at the floor; a [`graph`](#graph): the function's blocks | | | [`lens`](#lenses) | a drawing of some state over the program's two columns, and in the third the pane it is a view of | `beside`, `subject` | | | [`hexdump`](#hexdump) | memory, a `bytes` row a line | typed or by `fields`; `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) `pages` | the drawings a lens can hold | `nodes` in two rows, a `bin` heading the second | +| | [`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 | | 4 tie | [`thread`](#4-ties) | the current line is these instructions | standing | | | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin`; a stub when that is out of view | | | [`projection`](#4-ties) | these bytes are that part of the drawing | for a step | | | [`echo`](#4-ties) | the same mark in two panels at once | for a step | | 5 frame | [`stage`](#5-the-frame) | the working frame: the band and the two columns | split `none`, `beside`, `subject` | +| | [`pair`](#pair) | two runs of one program against each other, a seam between them | `only here`, `differs`; the shadow on an ASan run's stack | | | [`map`](#the-map-and-the-minimap) | the working frame unfolded, every panel whole: 3840 by 2160 | the key | | | [`minimap`](#the-map-and-the-minimap) | the map at a twentieth, in the working frame's corner | windows, marks, `flash` | | | [`clock`](#clock-and-caption) | where in the recording | | @@ -93,6 +94,7 @@ this table. | 6 verb | [`fire` `arm` `strike` `cool` `read` `extend` `link` `project` `travel` `advance`](#6-verbs) | what one block does | | | | [`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 | | +| | [`leave` `turn` `spread` `gather`](#6-verbs) | what a graph does: a block left by an edge, a loop's turn, rows into blocks and back | | | | [`dive` `surface` `flash`](#6-verbs) | between the map and the working frame | | | | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | @@ -426,6 +428,7 @@ A word of the stack, pwndbg's way and a little more. | 16 | pins | the `row` pin's lane, to 112: every register whose value is this word's address | | 172 | offset | from rsp, hex, `+18`, faint, ranged right in four characters (`-8` above rsp) | | 184 | address | stack ink, `lead`; then the chain, its first hop the word's content | +| 88 | shadow | in a run built with AddressSanitizer: the shadow byte that stands for this word's eight bytes, a `byte` cell in the pin lane's end, before the address it stands for (a fake frame's words have no offset from rsp, and no pins). `00`, addressable: faint, no paper. `f1` `f2` `f3`, the stack's left, middle and right redzones: bright on the `freed` hatch, the poison's sign. `01` to `07`, the first k bytes addressable: bright, the hatch over the other 8 − k eighths of its cell. The panel's tag gives where the shadow is, `shadow at addr >> 3 + 7fff8000` | | right | role | what the word is, where the recording knows it, ranged right where the chain's room ends: `saved rbp`, `saved rbx` (dim); a local's name (primary), and which part of the word when it is narrower (`n, high half`); at the process's start `argc`, `argv[0]`, `argv end`, `envp end`, `auxv` (dim) | | 14 from the right | span | the [`call`](#call) bracket, its name left of it | @@ -782,6 +785,91 @@ kernel's head and two rows ([mock 16](mock/16-descent.png)). 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. It is drawn with its rows at the map's size +(the larger scale), and as shapes in the working frame's `blocks` lens. +Execution flows down; the one thing that climbs is a loop's back edge. + +| Part | Drawn | +| --- | --- | +| a block | a box of `insn` rows, a 2-unit `rule` frame; a head of 24, raised: its first address in code ink, its lines (Go 18, faint), ranged right how many times the run has entered it (`×11`, primary). Not yet reached at the moment shown: its head on the page, no count. The pc's: a 2-unit gold frame | +| its rows | the offset from the function's start (`+65`, faint, ranged right at 72) in place of the address, which the head carries; 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 block (and its rows that ran in the last three steps). As wide as its widest row, 300 at least | +| a long block | 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: a hook out of the block's right side at the call's row and back in a row down (2, `dim`), the callee's name after it (`swap`) | +| the way out | under a block that returns, a stub 14 down and a bar 28 wide | +| a forward edge | taken, not taken, a jump, a fall-through: out of the block's bottom on the side its target lies on (40 in from that side, or the middle when it is straight below), along the middle of the gap under its layer, into the target's top; several into one top 48 apart in their sources' order; corners 8. One that would cross a block runs in the graph's right channel, 32 right of its widest layer | +| 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. No hue says it | +| a back edge | an edge to a block at its own layer or above: a loop. Out of the bottom, down 14, left to its loop's lane (left of every block, 16 apart, the outermost farthest), up it, into the header's head from the left. Its turns so far on the lane under the turn in, Go 18 faint (`×5`); a turn landing strikes 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 down from the block's bottom and the function it goes to, its name in primary; no bar, since the function does not end here but in the one it jumped to | +| 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 recording: `rule`, 2. Taken: `dim`, 2, the run's count by a conditional's ports (`10`, `7`). The last three taken: the trail's golds, the newest 3 units | + +**Layout.** Back edges are found by a walk from the entry in address +order; every other edge goes down a layer or more: each block one layer +under the deepest that leads to it, and the blocks that return in the +last. In a layer a block sits under the predecessor that reached it most +often in the recording, so the hot path is straight down; then under the +fall-through's; a taken target to the right of it; then the order that +crosses fewest edges. A loop's body hangs between its header and the +block that turns back, right of its lane; nested loops nest their lanes. +Layers 48 apart, blocks 56 apart, lanes 16 apart from 24 inside the panel. + +**Too big for its place**, in this order: the blocks the whole recording +never reached fold, each connected run of them one dashed box, its +offsets and its count (`+5b to +b3 · 4 blocks never reached`) and, where +the scene names it, what it is (`multi-threaded: a cancellable call`); long +blocks fold; a loop the pc is not in and will not enter again folds to +one box (`loop at +5f · 3 blocks · 11 turns`); then the panel pans by +`scroll`'s rules, the pc's block in its middle third. + +**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 shapes, on the map too. 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. + +**Where it lives.** + +- **The map** draws the disassembly column in this form whenever the + recording has the function's blocks (the linear 69 rows otherwise, or + when the scene asks), two columns wide (1792); the panels after it + repack. The source is beside it; the thread is its digits (the gold + line number in the pc's block and the source's plaque): no line crosses + the lanes. A descent on the map stacks graphs: a caller folded to the + block that holds its waiting call and one block either side, the + callee's graph whole under it, the kernel's window under that. +- **The minimap** shows it at a twentieth: block outlines, row strokes, + edges 1 px, the pc's block gold. A sprint on the map reads there as the + gold going from block to block. +- **The working frame** keeps the linear rows (rule 6) and shows their + blocks: a 2-unit `rule` across over each block's first row, and the + block's visits ranged right in that row's annotation room (`×11`, + faint) when it is free. The graph with its rows is not drawn there: two + blocks' rows barely fit side by side in 880, and the same rows twice + are noise. +- **The `blocks` lens**, for a scene about control flow: its drawing the + graph without text, a block a box 24 high, as wide as its rows (10 a + row, 132 at least), its offset and visits, the pc's framed gold 3, the + edges, lanes and trail at half measure (layer gap 12, lanes 10 apart); + its view, over the state column, is the disassembly itself, seven rows + round the pc (five beside), moved out of the program column, which then + holds the source alone (twenty lines as subject). No row is drawn + twice: the box is the place, the view the text, and the pc's gold is on + both. + +Its motion is [`leave`, `turn`, `spread`, `gather`](#6-verbs). Mocks 22 to 25. + ### lenses A lens is the band across the top of the stage: **a drawing, over the @@ -1228,6 +1316,50 @@ What stays, and why: a tree down, the far view's time left to right, a loupe hung under its pointer. None goes against the rules. +### pair + +Two runs of one program seen against each other: two builds (plain and +with AddressSanitizer), two versions, two C libraries, two inputs. It is +a split of the working frame, and general: the shared panels are drawn +once, the ones that differ twice, one on each side of a seam. + +| Of the frame | Drawn | +| --- | --- | +| the seam | the gutter between the columns (944 to 976): the left column is one run, the right the other, each panel's tag naming its run (`plain · disassembly`, `asan · disassembly`). Down is still deeper in each; across the seam is the other run | +| the source | shared when both runs are the same file: one panel across both columns, 1792 wide, five lines (48 to 200). Each run's current line is marked on its own side of it: the left run's gold plaque on the number at the left, the right run's ranged right at the panel's right edge, the wash across the row once when both are on it. Two files: two panels, as below | +| each column | its run's context cut to what the scene's line touches: its disassembly, nine rows (212 to 460); the registers the line reads or writes and rip, rsp, rbp, four rows (472 to 600); the stack frame from rsp to the return address, ten rows (612 to 884). A run built with ASan adds the shadow to its stack's rows ([`slot`](#slot)) | +| alignment | the two disassemblies are scrolled so that the current line's first row is at one height on both; below it each runs on. The two stacks are scrolled so that the same variable's first row (`buf`) is at one height. Corresponding things face each other across the seam | +| only here | a row one run has and the other has not (the instrumentation; a function only one build calls): a 4-unit `dim` bar on its seam-side edge. Its counterpart is the page facing it, or nothing | +| differs | a value that differs from its counterpart at the same step (the saved rbp kept on one side and overwritten on the other): a 4-unit `bright` bar on its seam-side edge, on both sides. It is the difference across runs; a strike is a change in time, and both can stand together | +| the clock | one rule, counting the pair's steps; under it, ranged right, each run's moment: `plain moment 61 · asan moment 412` | +| the caption | one, for the pair: it narrates the difference | +| the minimap | both runs' maps at a fortieth, side by side in its box (96 by 54 each), each with its windows. The map itself is one run's at a time: a `surface` goes to the side in focus | + +**Keeping the two in step.** A pair's step is one source line in both +runs, or one turn of a loop when the narration says so: the unit both +share. Inside it each side walks its own instructions; their cascades +share the levels (CPU, memory, the idea), and the side with more rows +sets the step's length, its rows 6 f apart, the other side's spread over +the same time. Its first time through, a row only one run has (ASan's +check before a store) is walked row by row as any step, the other side +holding still with its plaque on the row that faces it; after that, at a +run inside the step. When one run stops (a report, a crash, an exit) and +the other goes on, the stopped side holds its last picture, unveiled, +and the steps go on in the other alone. + +**When they part** is the scene's point: the first step in which the two +runs do different things (one stores, the other branches to a report). +That step is walked; its two sides' first different rows are framed +`attention`, one each side, and nothing else moves until both have +struck. + +A run that writes to stderr (ASan's report) shows it in its own column, in +place of its registers and its disassembly's lower rows once it has +stopped: a panel of the run's output, its lines as written, the ones the +narration names framed. + +Mocks 26 to 28; [the scene](motion.md#a-scene-asan-against-a-plain-build). + ### The map and the minimap **The map** is the working frame unfolded: every panel at its full length, @@ -1357,11 +1489,14 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves: | `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 an edge | 0 to 12 fire on its last row; 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 port to the target, head first, `standard`; then the mark travels it: the gold plaque leaves the row along the edge, `glide`, 12 f and 2 f a 100 units, 30 f at most, the row cooling to the trail as it goes; it lands on the target's first row (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` along the lane: out of the bottom, out to the lane, up it, in at the header's head; the lane's count struck as the mark goes in | +| `spread` | the rows into a graph (on the map, or in a `dive` or `surface` between a graph and the working frame's rows) | 0 to 36 every row glides from its place in the column to its place in its block, `glide`, the blocks 4 f apart in layer order; nothing fades while rows travel; 36 to 48 the blocks' frames and heads fade in round them; 48 to 72 the edges draw, layer by layer, 2 f apart, 12 f each. `gather` is the reverse: edges out (12 f), frames and heads out (12 f), then the rows glide home (36 f) | | `arc` | a pointer to a row of its panel | written: with the arm (s−12) the old arc goes dashed; from s+6 it fades (12 f) while the new one draws from the pointer's row along its lane to the target, head first, 12 f, `standard`, at full ink; with the cool at the advance it quiets to standing (24 f). Read: to full ink with the read (6 f), back with the advance. Overwritten with a target off the panel or NULL: it fades from s+6 (12 f). A lane change glides 12 f. Scrolled: it rides its rows, fading as its target leaves. At a run 8 f, at a sprint none | | `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 | 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, 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 lanes' counts ticking, 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 minimap's 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's outline on the minimap glides with it, the same 24 f. 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 (ten lines, nine instructions, six slots) 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 | @@ -1446,7 +1581,9 @@ 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/heap.py` draws the heap scene's storyboard (18) from a +(15); `mock/graph.py` draws the graphs (22 to 25) from `sort-O0.dis`, +`reverse-O0.dis` and `libc-open.dis` and the paths their runs took; +`mock/heap.py` draws the heap scene's storyboard (18) from a recording of `mock/heap.c`; `mock/gen.py` draws 1 to 8. Each working frame has a `-480.png` beside it; the map has its 1080p (`19-map-1080.png`). @@ -1456,6 +1593,8 @@ 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 25-blocks-lens; do resvg $n.svg $n.png; done +python3 -B pair.py && for n in 26-pair-rest 27-pair-store 28-pair-part; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done python3 -B dense.py && resvg 15-marks.svg 15-marks.png python3 -B map.py && for n in 09-context 10-context-step 11-context-lens 21-loupe 19-map; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done # 20-dive.png it composes itself @@ -1479,6 +1618,13 @@ 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 `graph`, two columns wide beside the source, at moment 370 of the stepped run (the sixth pass, its third compare) | blocks with heads, offsets, lines, visits; the pc's block gold with its annotations (a compare's values and flags, the `jg` reading them); the inner and outer loops' back edges climbing their lanes with their turns; a conditional's counts by its ports; the edge never taken (`jle` to the next pass) in `rule`; the right channel; a call's hook (`swap`); the exit not yet reached | +| [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 boxes by what they are | folds of unreached blocks, named; blocks the run will reach but has not yet, plain; twelve-digit heads, offsets in the rows | +| [24](mock/24-graph-strip.png) | reverse's loop, four instants | `leave`: the condition's chips, the edge lit, the mark halfway along it; `turn`: the back edge climbing with the mark on it, its count struck; the way out | +| [25](mock/25-blocks-lens.png) | sort at moment 370 in the working frame with the `blocks` lens | the graph as shapes in the band, the pc's box gold, the trail; its view the disassembly round the pc, out of the program column, which holds the source alone; registers and stack of the moment | +| [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; plain's stack with the red zone's `buf` and `i`, ASan's fake frame with its shadow on each word's row, `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 | +| [28](mock/28-pair-part.png) | i = 16, the step in which they part | plain's store struck into the saved rbp's low byte; ASan's shadow load framed reading `f3`, its compare and the branch not taken; `differs` on the facing rows | | [1](mock/01-fib-recursion.png) | first pass | `calls` at camera scale | | [2](mock/02-list-insert.png) | first pass | `nodes` at camera scale; `allocated` | | [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` (the kernel's side is now the descent's floor, 16) | @@ -1589,7 +1735,22 @@ 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. **Still from before**: the calls tree's small size and folds, +7. **The graph** ([`graph`](#graph)): basic blocks from the recording, + the layered layout (back edges by a walk from the entry, layers by the + longest path, the hot path straight down, loops' lanes on the left, the + right channel), blocks with heads and offset rows, the edges' ink by + what the run did, folds (never reached, long blocks, finished loops), + pan; on the map in place of the linear column, two columns wide; the + linear form's block rules and counts; the `blocks` lens with the + disassembly as its view; `leave`, `turn`, `spread`, `gather`; the run + and the sprint over it. +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`, the shadow on an ASan + run's stack rows, one clock with two moment counts, two minimaps at a + fortieth, the stopped side holding, a run's stderr as a panel; steps + matched by source line or loop turn. +9. **Still from before**: the calls tree's small size and folds, `metric.span.name_max` 300, `time.caption_max` 12 s and `time.first_step` 4 s (5 s when a scene opens on the map), `time.dive` and `time.flash`. @@ -1618,6 +1779,21 @@ is not checked here. The tokens are under [Token changes](#token-changes). ReleaseFast build used here (`hello`, 120 moments, all in `ld.so`): `--from` did not take; `dbg` with a breakpoint was used instead. - For the heap scene: see [the scene](motion.md#a-scene-libcs-heap-from-the-inside). +- For a pair (the ASan scene): see [the scene](motion.md#a-scene-asan-against-a-plain-build). +- **For the graph**, per function and once: its blocks (first and last + address, how each ends: a conditional jump, a jump, an indirect jump, a + return, a call that does not return, or a fall into the next), each + block's edges with their kind and target, the calls in it and their + callees, and an indirect jump's table where it can be read. Calls that + do not return must be known by name (`__stack_chk_fail`, + `__syscall_do_cancel`, `abort`, `exit`), and instruction prefixes + (`addr32 call`, `notrack jmp`, `bnd jmp`) read through, or a block runs + on into the next and makes a false loop (it did in this round's first + try at libc's `open`). Per stop: the visits to each block and the count + of each edge so far (the renderer can count them from the `branch` + events, if every taken branch and fall-through between blocks is + there), and, for the folds, which blocks the whole recording ever + reaches. For a descent in graph form, each frame's function's blocks. ## Token changes @@ -1639,6 +1815,9 @@ loupe's and the arc's tokens, the lift's colours, the clock's count at | `metric.node.two_rows`, `metric.bin` | none | rows 110 apart, nodes 136 wide; the bin box 160 by 44 at the row's left, its count on a 30 square on the shoulder; a free node's outline dashed 12 on 8 | | `time.descend` | none | `close` 0.20 then 0.30 (`glide`), `ring` 0.20, `lane` 0.30, `head` 0.20, `rows` 0.20 a row 0.03 apart, from 1.10 after the fire, the given-up rows fading before the kept glide, never both; the step 2.90 | | `time.cross` | none | the registers framed 0.10 apart from 0.30; `lane` 0.40 from 0.80; the kernel's window 0.20; the answer up 0.40; the step 3.60, 4.90 when it moves bytes | +| `metric.graph` | none | a block's head 24; rows: offset ranged right at 72, line at 116, mnemonic at 128, operands at 212; 300 wide at least; fold past 16 rows to 4, `more`, 4; layers 48 apart, blocks 56, lanes 16 from 24; back edge down 14; port 40 in; arrivals 48 apart; right channel 32 out; corners 8; the exit's stub 14 and bar 28; a call's hook 14 out, a row down. Lens: boxes 24 high, 10 a row, 132 at least; layer gap 12; lanes 10 | +| `time.leave` | none | chips 0.10 from 0.30; the edge 0.30; the mark 0.20 and 0.033 a 100 units, 0.50 at most; the count struck 0.10 after landing; the trail's cool 0.30; at a run 0.13 | +| `time.spread` | none | rows 0.60 (`glide`, blocks 0.067 apart), then frames 0.20, then edges 0.20 each, 0.033 apart | | `time.ascend` | none | `close` 0.20 a row, 0.03 apart, from 0.80; the lane back 0.20; the caller's kept rows 0.30 (`glide`), then the given-back rows 0.20; the step 2.50 | Unchanged and already there: the 1920 stage and its splits, the palette |
