diff options
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 70 |
1 files changed, 69 insertions, 1 deletions
diff --git a/design/README.md b/design/README.md index 9bae30b..ffbb820 100644 --- a/design/README.md +++ b/design/README.md @@ -84,6 +84,8 @@ this table. | | [`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` | +| | [`segments`](#segments) | the process's address space, its mappings a row each | the ink's source; a mapping framed when a word is inked | +| | [`aligned`](#aligned) | the source and the disassembly side by side, each line level with its code | a split a scene chooses | | | [`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` | @@ -94,6 +96,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 | | +| | [`regroup` `ink` `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 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 | | @@ -1316,6 +1319,48 @@ 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. +### segments + +The process's address space, which is where the inks come from: a panel +of its mappings as the recording has them, low addresses on top, a row +each. A bar 8 wide in the mapping's ink, its first address, its file or +name (`list`, `heap`, `libc.so.6`, `[vdso]`, `[stack]`), what it is (code, +read-only data, data, malloc's, the stack: from its permissions), its +size ranged right (`4 KiB`, `1.5 MiB`). Rows, not a scale: the code and +the stack are 127 TiB apart, and a hole between mappings is one row, a +faint zig-zag and its size (`nothing mapped · 127 TiB`). When a word takes +its ink, the mapping it points into is framed as read with it (an +`echo`). It is the legend's long form: the registers' tag carries its +inks in short; the title card's legend and the map's key draw this panel. +It is not the far view (mock 8), which is time over pages; the far view +can stand on it as its axis. Mock 30. + +### aligned + +The source and the disassembly side by side, a table in address order: +each source line level with the first row of its instructions, a quiet +bracket by the gutter from the line down its run's last row. A line whose +code comes in several runs (a `for`'s test and step, a `while` tested +before and after its body, code the compiler moved) is drawn at its first +run and repeated faint at each other; a line with no code of its own is +not drawn, and the gap in the numbers says so (the scene's caption may); +instructions of no line (padding, another function without source) have +the function's name beside them, faint. The pc's row and its line are one +band across both columns and the gutter: the alignment is the thread, so +no thread is drawn. A call followed down puts the callee's lines beside +the callee's rows, under the caller's waiting call (the `descent`, both +columns at once). + +It is a split a scene chooses, and the default nowhere: the program +column becomes the source (left, 880) and the state column the +disassembly (right, 880), the band and the registers and stack giving way +for as long as it lasts. Across the gutter is "the same thing one level +down", as in the band; down is still deeper in each column. Reach for it +to teach what a line compiles to, in the introduction, and in a pair (the +source in the middle, 586 wide, each build's rows aligned to it on its +side). The two columns scroll as one. `align` and `stack` change between +it and the stacked form. Mocks 32 and 33. + ### pair Two runs of one program seen against each other: two builds (plain and @@ -1492,6 +1537,12 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves: | `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) | +| `regroup` | bytes into a word (the introduction) | the eight bytes of a word slide together and reverse in place, the low byte to the right (24 f, `glide`), the spaces between them closing; the word's digits fade in over them as they land (12 f), the bytes staying behind, faint, for the rest of the beat. The first walked, the rest at a run (8 f each) | +| `ink` | a word becoming an address | its digits go from primary to its region's ink (12 f), and the mapping it points into in `segments` is framed as read (6 f): an echo, no line | +| `column` | rows gaining a column (offsets, roles, pins, lines) | the rows make room (18 f, as rows do), then the column's values fade in top down, 2 f apart, 12 f each | +| `frame up` | a panel arriving round rows already built | its rule draws round them (12 f), then its tag fades in (12 f): the last thing, never the first | +| `decode` | an instruction's bytes becoming its row | the bytes of one instruction gather (12 f), the mnemonic and operands fade in beside them (12 f), and the bytes dim; the row then travels to its place (`glide`, 24 f) | +| `align` | the stacked program column to `aligned`, and back (`stack`) | the band and the state column fade out (12 f); the disassembly glides from under the source to beside it (36 f, `glide`); then the source's lines glide apart to their instructions' rows (24 f, rows making room) and the run brackets fade in (12 f). `stack` is the reverse | | `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 | @@ -1595,6 +1646,7 @@ 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 intro.py && for n in 29-intro-bytes 30-intro-words 31-intro-stack 32-intro-code 33-aligned; do resvg $n.svg $n.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 @@ -1625,6 +1677,11 @@ python3 -B gen.py # 1 to 8, then resvg the same way | [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 | +| [29](mock/29-intro-bytes.png) | the introduction's first picture, the camera at x2: 128 bytes of the stack, nothing else | a raw hexdump, before any ink | +| [30](mock/30-intro-words.png) | eight bytes a row, each row's word read right to left beside it, inked; the address space beside | `regroup` landed; `ink`; `segments`, the code mapping framed for the return address | +| [31](mock/31-intro-stack.png) | the same words as the stack panel, the registers built over it, at x1.25 | the stack's conventions: rsp and rbp pins, offsets, roles, spans | +| [32](mock/32-intro-code.png) | the code chapter: `aligned` with each instruction's bytes between its address and mnemonic | an instruction as bytes, decoded, level with its line | +| [33](mock/33-aligned.png) | the `aligned` split: reverse and its neighbours, the pc at the load | a line with two runs (20), lines with no code, rows of no line, the band as the thread | | [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) | @@ -1750,7 +1807,11 @@ is not checked here. The tokens are under [Token changes](#token-changes). 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, +9. **The introduction's blocks** ([`segments`](#segments), [`aligned`](#aligned)): + the address space from the mappings; the aligned split; `regroup`, + `ink`, `column`, `frame up`, `decode`, `align`; a hexdump with no ink + (the first picture only). +10. **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`. @@ -1780,6 +1841,13 @@ is not checked here. The tokens are under [Token changes](#token-changes). `--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 introduction: the mappings with their permissions and their + file offsets (to say code, read-only data, data), not only their ranges + and paths (`ztrace show` prints ranges and paths); the bytes of the + instructions in the window (or the binary, for the renderer to read + them); and a recording of the program by instruction from `main` to the + stop, so that a real `push`, a real `call` and the moment rsp moves are + shown, not described. - **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 |
