From beb2616a243e01826c3103209d5525381a5da73d Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 11 Nov 2026 11:27:09 -0300 Subject: design: an introduction that builds the views; segments; source and disassembly aligned From the user. Three short chapters teach the frame by assembling it: bytes become words, words that are addresses take the ink of the mapping they point into, the stack's conventions are shown on those same rows by a real push and call, an instruction's bytes decode into its row beside its source line, and the working frame stands at the end. segments is the process's mappings as rows, the legend's long form. aligned is a split a scene chooses: each source line level with the first row of its instructions. Verbs for building a view: regroup, ink, column, frame up, decode, align. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- design/README.md | 70 +++++++++++- design/mock/29-intro-bytes.png | Bin 0 -> 83086 bytes design/mock/29-intro-bytes.svg | 145 ++++++++++++++++++++++++ design/mock/30-intro-words.png | Bin 0 -> 224784 bytes design/mock/30-intro-words.svg | 246 +++++++++++++++++++++++++++++++++++++++++ design/mock/31-intro-stack.png | Bin 0 -> 144165 bytes design/mock/31-intro-stack.svg | 207 ++++++++++++++++++++++++++++++++++ design/mock/32-intro-code.png | Bin 0 -> 104319 bytes design/mock/32-intro-code.svg | 155 ++++++++++++++++++++++++++ design/mock/33-aligned-480.png | Bin 0 -> 18796 bytes design/mock/33-aligned.png | Bin 0 -> 135867 bytes design/mock/33-aligned.svg | 198 +++++++++++++++++++++++++++++++++ design/mock/intro.py | 217 ++++++++++++++++++++++++++++++++++++ design/motion.md | 54 +++++++++ 14 files changed, 1291 insertions(+), 1 deletion(-) create mode 100644 design/mock/29-intro-bytes.png create mode 100644 design/mock/29-intro-bytes.svg create mode 100644 design/mock/30-intro-words.png create mode 100644 design/mock/30-intro-words.svg create mode 100644 design/mock/31-intro-stack.png create mode 100644 design/mock/31-intro-stack.svg create mode 100644 design/mock/32-intro-code.png create mode 100644 design/mock/32-intro-code.svg create mode 100644 design/mock/33-aligned-480.png create mode 100644 design/mock/33-aligned.png create mode 100644 design/mock/33-aligned.svg create mode 100644 design/mock/intro.py (limited to 'design') 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 diff --git a/design/mock/29-intro-bytes.png b/design/mock/29-intro-bytes.png new file mode 100644 index 0000000..e382abe Binary files /dev/null and b/design/mock/29-intro-bytes.png differ diff --git a/design/mock/29-intro-bytes.svg b/design/mock/29-intro-bytes.svg new file mode 100644 index 0000000..fcd07cc --- /dev/null +++ b/design/mock/29-intro-bytes.svg @@ -0,0 +1,145 @@ + + + + +128 bytes, from where rsp points +7fffffffece0 +00 +ed +ff +ff +ff +7f +00 +00 +b0 +18 +00 +01 +00 +00 +00 +00 +7fffffffecf0 +e8 +0d +e2 +f7 +ff +7f +00 +00 +00 +00 +00 +00 +00 +00 +00 +00 +7fffffffed00 +b0 +ed +ff +ff +ff +7f +00 +00 +81 +77 +c2 +f7 +ff +7f +00 +00 +7fffffffed10 +60 +0c +fe +f7 +ff +7f +00 +00 +38 +ee +ff +ff +ff +7f +00 +00 +7fffffffed20 +00 +e0 +fb +f7 +01 +00 +00 +00 +60 +18 +00 +01 +00 +00 +00 +00 +7fffffffed30 +70 +ed +ff +ff +ff +7f +00 +00 +60 +f2 +fd +f7 +ff +7f +00 +00 +7fffffffed40 +00 +00 +00 +00 +00 +00 +00 +00 +1c +78 +a5 +95 +fc +35 +e3 +1f +7fffffffed50 +38 +ee +ff +ff +ff +7f +00 +00 +01 +00 +00 +00 +00 +00 +00 +00 + +A running program is bytes in memory. +These are 128 of them, sixteen to a row. + diff --git a/design/mock/30-intro-words.png b/design/mock/30-intro-words.png new file mode 100644 index 0000000..faba6f4 Binary files /dev/null and b/design/mock/30-intro-words.png differ diff --git a/design/mock/30-intro-words.svg b/design/mock/30-intro-words.svg new file mode 100644 index 0000000..fd1502b --- /dev/null +++ b/design/mock/30-intro-words.svg @@ -0,0 +1,246 @@ + + + + +eight bytes a row, read right to left, a word +7fffffffece0 +00 +ed +ff +ff +ff +7f +00 +00 +7fffffffed00 +7fffffffece8 +b0 +18 +00 +01 +00 +00 +00 +00 +10018b0 +7fffffffecf0 +e8 +0d +e2 +f7 +ff +7f +00 +00 +7ffff7e20de8 +7fffffffecf8 +00 +00 +00 +00 +00 +00 +00 +00 +0 +7fffffffed00 +b0 +ed +ff +ff +ff +7f +00 +00 +7fffffffedb0 +7fffffffed08 +81 +77 +c2 +f7 +ff +7f +00 +00 +7ffff7c27781 +7fffffffed10 +60 +0c +fe +f7 +ff +7f +00 +00 +7ffff7fe0c60 +7fffffffed18 +38 +ee +ff +ff +ff +7f +00 +00 +7fffffffee38 +7fffffffed20 +00 +e0 +fb +f7 +01 +00 +00 +00 +1f7fbe000 +7fffffffed28 +60 +18 +00 +01 +00 +00 +00 +00 +1001860 +7fffffffed30 +70 +ed +ff +ff +ff +7f +00 +00 +7fffffffed70 +7fffffffed38 +60 +f2 +fd +f7 +ff +7f +00 +00 +7ffff7fdf260 +7fffffffed40 +00 +00 +00 +00 +00 +00 +00 +00 +0 +7fffffffed48 +1c +78 +a5 +95 +fc +35 +e3 +1f +1fe335fc95a5781c +7fffffffed50 +38 +ee +ff +ff +ff +7f +00 +00 +7fffffffee38 +7fffffffed58 +01 +00 +00 +00 +00 +00 +00 +00 +1 + + + + + +the address space +the recording's mappings, low on top + +1000000 +list +headers, read-only +4 KiB + +1001000 +list +code +4 KiB + + +1002000 +list +read-only data +4 KiB + +1003000 +list +data +4 KiB + +1004000 +heap +malloc's +132 KiB + +nothing mapped · 127 TiB + +7ffff7c00000 +libc.so.6 +read-only +144 KiB + +7ffff7c24000 +libc.so.6 +code +1.5 MiB + +7ffff7d9f000 +libc.so.6 +read-only data +472 KiB + +7ffff7e15000 +libc.so.6 +data +56 KiB + +7ffff7fbc000 +[vdso] +code +8 KiB + +7ffff7fbf000 +ld.so +code +180 KiB + +7ffff7ffb000 +ld.so +data +16 KiB + +nothing mapped · 127 MiB + +7ffffffde000 +[stack] +the stack +132 KiB + +Eight bytes make a word, stored low byte first: read right to left, +this one is 10018b0, an address in the code, so it takes code's ink. + diff --git a/design/mock/31-intro-stack.png b/design/mock/31-intro-stack.png new file mode 100644 index 0000000..a85abd2 Binary files /dev/null and b/design/mock/31-intro-stack.png differ diff --git a/design/mock/31-intro-stack.svg b/design/mock/31-intro-stack.svg new file mode 100644 index 0000000..e3eadcd --- /dev/null +++ b/design/mock/31-intro-stack.svg @@ -0,0 +1,207 @@ + + + + + + + +registers +stack +heap +code +data +rwx + +read-only +rax +1004090 + + +4 +rbx +0 +rcx +10040b0 + + +1 +rdx +0 +rsi +10040c0 + + +0 +rdi +1004090 + + +4 +rbp +7fffffffece0 + + +7fffffffed00 + + +7fffffffedb0 + + +7fffffffee10 + + +0 +rsp +7fffffffece0 + + +7fffffffed00 + + +7fffffffedb0 + + +7fffffffee10 + + +0 +r8 +7ffff7e19ac0 +r9 +0x20 +32 +r10 +0x10 +16 +r11 +7ffff7e19ac8 +r12 +7fffffffee38 + + +7fffffffefea + + +"./list" +r13 +1 +r14 +7ffff7ffd000 + + +7ffff7ffe3c0 + + +0 +r15 +10029c0 + + +1 + + +rip +1001926 +reverse+22 +cf + +PF +af +zf +sf + +IF +df +of + + + +stack +eight words from rsp · the frames they belong to +rbp rsp + ++0 +saved rbp +7fffffffe +ce0 + + +7fffffffed00 + + + + + ++8 +7fffffffe +ce8 + + +10018b0 +main+80 ++10 +7fffffffe +cf0 + + +7ffff7e20de8 ++18 +saved rbx +7fffffffe +cf8 + + +0 ++20 +saved rbp +7fffffffe +d00 + + +7fffffffedb0 + + + + + ++28 +7fffffffe +d08 + + +7ffff7c27781 +libc+27781 ++30 +7fffffffe +d10 + + +7ffff7fe0c60 +ld.so+22c60 ++38 +7fffffffe +d18 + + +7fffffffee38 + + +7fffffffefea + + +".… + + + +reverse + + + +main + + +libc+27781 + +The same words as the stack: rsp points at its top, each word +has its offset, a frame is a span, and the registers sit over it. + diff --git a/design/mock/32-intro-code.png b/design/mock/32-intro-code.png new file mode 100644 index 0000000..eb22ba7 Binary files /dev/null and b/design/mock/32-intro-code.png differ diff --git a/design/mock/32-intro-code.svg b/design/mock/32-intro-code.svg new file mode 100644 index 0000000..35597b8 --- /dev/null +++ b/design/mock/32-intro-code.svg @@ -0,0 +1,155 @@ + + + + + + +list.c +each line beside the first of its instructions + + + +disassembly +reverse + + + + + + + + + + + + + + + +20 +while +( +head +) +{ +10019 +10 +48 85 ff +test +rdi, rdi +10019 +13 +74 20 +je +1001935 +10019 +15 +55 +push +rbp +10019 +16 +48 89 e5 +mov +rbp, rsp +10019 +19 +31 c0 +xor +eax, eax +10019 +1b +0f 1f 44 00 00 +nop +[rax + rax] +10019 +20 +48 89 c1 +mov +rcx, rax +10019 +23 +48 89 f8 +mov +rax, rdi + + + + + + +21 +struct +node +* +next += +head +- +> +next +; +10019 +26 +48 8b 7f 08 +mov +rdi, [rdi + 8] +1004098 + + +1004070 + + +9 +22 +head +- +> +next += +prev +; +10019 +2a +48 89 48 08 +mov +[rax + 8], rcx +20 +while (head) { +10019 +2e +48 85 ff +test +rdi, rdi +10019 +31 +75 ed +jne +1001920 +10019 +33 +5d +pop +rbp +26 +return +prev +; +10019 +34 +c3 +ret + +10019 +35 +31 c0 +xor +eax, eax +10019 +37 +c3 +ret + +48 8b 7f 08 is one instruction: mov rdi, [rdi + 8], line 21's +head->next. The line sits level with its code: they are one row. + diff --git a/design/mock/33-aligned-480.png b/design/mock/33-aligned-480.png new file mode 100644 index 0000000..a54620d Binary files /dev/null and b/design/mock/33-aligned-480.png differ diff --git a/design/mock/33-aligned.png b/design/mock/33-aligned.png new file mode 100644 index 0000000..5ed74b0 Binary files /dev/null and b/design/mock/33-aligned.png differ diff --git a/design/mock/33-aligned.svg b/design/mock/33-aligned.svg new file mode 100644 index 0000000..5c46e27 --- /dev/null +++ b/design/mock/33-aligned.svg @@ -0,0 +1,198 @@ + + + + + + +list.c +each line beside the first of its instructions + + + +disassembly +reverse + + + + + + + + + + + + + + + +20 +while +( +head +) +{ +10019 +10 +test +rdi, rdi +10019 +13 +je +1001935 +10019 +15 +push +rbp +10019 +16 +mov +rbp, rsp +10019 +19 +xor +eax, eax +10019 +1b +nop +[rax + rax] +10019 +20 +mov +rcx, rax +10019 +23 +mov +rax, rdi + + + + + + +21 +struct +node +* +next += +head +- +> +next +; +10019 +26 +mov +rdi, [rdi + 8] +1004098 + + +1004070 + + +9 +22 +head +- +> +next += +prev +; +10019 +2a +mov +[rax + 8], rcx +20 +while (head) { +10019 +2e +test +rdi, rdi +10019 +31 +jne +1001920 +10019 +33 +pop +rbp +26 +return +prev +; +10019 +34 +ret + +10019 +35 +xor +eax, eax +10019 +37 +ret + +_init · no line +10019 +38 +endbr64 + +10019 +3c +sub +rsp, 8 +10019 +40 +mov +rax, [rip + 0x1231] +10019 +47 +test +rax, rax +10019 +4a +je +100194e +10019 +4c +call +rax +10019 +4e +add +rsp, 8 +10019 +52 +ret + +_fini · no line +10019 +54 +endbr64 + +10019 +58 +sub +rsp, 8 +10019 +5c +add +rsp, 8 +10019 +60 +ret + +strtol@plt-0x10 · no line +10019 +70 +push +[rip + 0x1222] +10019 +76 +jmp +[rip + 0x1224] +Line 20, while (head), has two runs: its test before the body +and again after it. Lines 23 to 25 have no code of their own. + diff --git a/design/mock/intro.py b/design/mock/intro.py new file mode 100644 index 0000000..b9c7d7d --- /dev/null +++ b/design/mock/intro.py @@ -0,0 +1,217 @@ +#!/usr/bin/env python3 +"""The introduction: the frame built from its bytes up, on the recording of targets/list that mocks 9 to 21 use +(list-dbg.txt: the stack from rsp, the heap, the registers; the code's bytes from objdump of the binary). Four +instants of the build, each as the camera frames it. + + python3 -B intro.py # 29-intro-bytes, 30-intro-words, 31-intro-stack, 32-intro-code (.svg) +""" +import gen +import dense as D +import context as C +from context import (PAGE, RAISED, RULE, VELLUM, BRIGHT, DIM, FAINT, GOLD, KW, CODE, STACK, DATA, HEAP, READ, + A, S, ROW, TAG, PAD, MONO, BOLD, b, ph, mix, Svg) + +RSP = D.RSP +MAPS = [(0x1000000, 0x1001000, "list", "headers, read-only", VELLUM), (0x1001000, 0x1002000, "list", "code", CODE), + (0x1002000, 0x1003000, "list", "read-only data", VELLUM), (0x1003000, 0x1004000, "list", "data", DATA), + (0x1004000, 0x1025000, "heap", "malloc's", HEAP), None, + (0x7ffff7c00000, 0x7ffff7c24000, "libc.so.6", "read-only", VELLUM), + (0x7ffff7c24000, 0x7ffff7d9f000, "libc.so.6", "code", CODE), + (0x7ffff7d9f000, 0x7ffff7e15000, "libc.so.6", "read-only data", VELLUM), + (0x7ffff7e15000, 0x7ffff7e23000, "libc.so.6", "data", DATA), (0x7ffff7fbc000, 0x7ffff7fbe000, "[vdso]", "code", CODE), + (0x7ffff7fbf000, 0x7ffff7fec000, "ld.so", "code", CODE), (0x7ffff7ffb000, 0x7ffff7fff000, "ld.so", "data", DATA), + None, (0x7ffffffde000, 0x7ffffffff000, "[stack]", "the stack", STACK)] +CODE_BYTES = [(0x1001920, "48 89 c1"), (0x1001923, "48 89 f8"), (0x1001926, "48 8b 7f 08"), (0x100192a, "48 89 48 08"), + (0x100192e, "48 85 ff"), (0x1001931, "75 ed")] + + +def size(n): + for unit, k in (("TiB", 1 << 40), ("GiB", 1 << 30), ("MiB", 1 << 20), ("KiB", 1 << 10)): + if n >= k: + v = n / k + return ("%d %s" if v == int(v) or v >= 10 else "%.1f %s") % (v, unit) + return "%d B" % n + + +def segments(g, x, y, w, hot=()): + """`segments`: the process's address space as its mappings, low addresses on top, a row each: a bar in the + region's ink, the first address, what it is, its size; a hole between them one row, how big it is. Rows, not + a scale: the stack and the code are 127 TiB apart. hot: the mappings framed as read (a word just inked).""" + rows = len(MAPS) + y0 = C.panel(g, x, y, w, rows, "the address space", note="the recording's mappings, low on top") + last = None + for i, m in enumerate(MAPS): + yy = y0 + i * ROW + if m is None: # a hole: what is not mapped + nxt = next(mm for mm in MAPS[i + 1:] if mm) + hole = nxt[0] - last + g.path(f"M{x + 14},{yy + 8} l6,4 l-6,4 l6,4", FAINT, 2) + g.t(x + 40, b(yy), "nothing mapped · %s" % size(hole), 18, FAINT, "sans") + continue + lo, hi, name, what, ink = m + g.rect(x + 12, yy + 3, 8, ROW - 6, ink) + C.addr(g, x + 32, yy, lo, ink) + g.t(x + 32 + 13 * A, b(yy), name, S, VELLUM, MONO) + g.t(x + 32 + 13 * A + 11 * A, b(yy), what, 18, DIM, "sans") + g.t(x + w - 12, b(yy), size(hi - lo), S, FAINT, MONO, "end") + if lo in hot: + g.frame(x + 6, yy, w - 12, ROW, READ, 2) + last = hi + return y0 + + +def camera(g, k, cx, cy): + """The camera at scale k on the point (cx, cy) of the frame: all drawing after this is through it.""" + g.o.append(f'') + + +def raw_dump(g, x, y, rows, per=16, words=False, inked=False): + """The stack's bytes from rsp, `per` to a row; with words, each row's eight bytes read right to left as the + word they make, beside them, in the ink of what it points into when inked. Returns the rows' y.""" + ys = [] + for r in range(rows): + a0, yy = RSP + per * r, y + r * ROW + ys.append(yy) + C.addr(g, x, yy, a0, STACK if inked else FAINT) + bx = x + 12 * A + 12 + vals = [D.MEM.get(a0 + k, 0) for k in range(per)] + for k, v in enumerate(vals): + g.t(bx + k * 30 + (12 if k >= 8 else 0), b(yy), "%02x" % v, S, + mix(VELLUM, PAGE, 0.5) if words else VELLUM, MONO) + if words: + w_ = D.word(a0) + ink = (D.region(w_) or VELLUM) if inked else VELLUM + g.t(bx + per * 30 + 24, b(yy), "%x" % w_ if w_ else "0", S, ink, MONO) + return ys + + +def frame_bytes(name): + """The first picture: bytes, nothing else; the camera at x2 on them, where the stack panel will be built.""" + gen.W, gen.H = 1920, 1080 + g = Svg() + g.o.append('') + g.t(0, -10, "128 bytes, from where rsp points", 18, FAINT, "sans") + raw_dump(g, 0, 0, 8) + g.o.append("") + gen.caption(g, [[("A running program is bytes in memory.",)], + [("These are 128 of them, sixteen to a row.",)]]) + g.save(name) + + +def frame_words(name): + """Eight bytes a row now, each row's word beside it, inked by where it points; the address space beside.""" + gen.W, gen.H = 1920, 1080 + g = Svg() + g.o.append('') + g.t(0, -10, "eight bytes a row, read right to left, a word", 18, FAINT, "sans") + ys = raw_dump(g, 0, 0, 16, per=8, words=True, inked=True) + k = 1 # 7fffffffece8: the return address, main+80 + g.frame(12 * A + 12 - 4, ys[k] - 1, 8 * 30 + 4, ROW + 2, READ, 2) + g.frame(12 * A + 12 + 8 * 30 + 24 - 6, ys[k] - 1, 7 * A + 12, ROW + 2, READ, 2) + segments(g, 12 * A + 12 + 8 * 30 + 24 + 13 * A + 36, -24, 560, hot={0x1001000}) + g.o.append("") + gen.caption(g, [[("Eight bytes make a word, stored low byte first: read right to left,",)], + [("this one is ",), ("10018b0", "mono"), (", an address in the code, so it takes code's ink.",)]]) + g.save(name) + + +def frame_stack(name): + gen.W, gen.H = 1920, 1080 + g = Svg() + camera(g, 1.25, 976 + 440, 212 + 330) + C.RX = 976 + C.registers(g, 212, D.regs(False), D.FLAGS, {}) + rows = [r for r in __import__("map").slot_rows(16, 8)] + C.stack(g, 664, rows, __import__("map").frames_from(16, 8), rsp=RSP, roles=__import__("map").roles_from(16, 8)) + g.o.append("") + gen.caption(g, [[("The same words as the stack: rsp points at its top, each word",)], + [("has its offset, a frame is a span, and the registers sit over it.",)]]) + g.save(name) + + +BYTES = {0x1001910: "48 85 ff", 0x1001913: "74 20", 0x1001915: "55", 0x1001916: "48 89 e5", 0x1001919: "31 c0", + 0x100191b: "0f 1f 44 00 00", 0x1001920: "48 89 c1", 0x1001923: "48 89 f8", 0x1001926: "48 8b 7f 08", + 0x100192a: "48 89 48 08", 0x100192e: "48 85 ff", 0x1001931: "75 ed", 0x1001933: "5d", 0x1001934: "c3", + 0x1001935: "31 c0", 0x1001937: "c3"} + + +def aligned(g, y, first, n, cur, cur_line, bytes_=False, title="reverse"): + """`aligned`: the source and the disassembly side by side, a table in address order: each source line level + with the first row of its run of instructions, a line that comes again (a second run) repeated faint at that + run, a line with no code of its own not drawn (its number missing says so), a row of no line (padding) with + nothing beside it. The pc's row and its line are one band across both columns: the alignment is the thread.""" + rows = [r for r in D.disasm_rows() if r[0] >= first][:n] + h = ph(n) + C.tag(g, 64, y, 880, h, "list.c", note="each line beside the first of its instructions") + C.tag(g, 976, y, 880, h, "disassembly", note=title) + y0 = y + TAG + PAD + seen, last_line = set(), None + lead = C.shared([r[0] for r in rows]) + i0 = 0 # each run's extent: a quiet bracket by the gutter, line to its last row + for i in range(1, n + 1): + if i == n or rows[i][2] != rows[i0][2]: + if rows[i0][2] is not None: + C.bracket(g, 932, y + TAG + PAD + i0 * ROW + 3, y + TAG + PAD + i * ROW - 3, RULE, 2, 5, side=-1) + i0 = i + for i, (a, func, line, mn, ops) in enumerate(rows): + yy = y0 + i * ROW + on = a == cur + if on: # one band through the gutter: the line and its instruction are one + g.rect(64 + 2, yy, 880 - 4, ROW, C.WASH) + g.rect(944, yy, 32, ROW, C.WASH) + g.rect(976 + 2, yy, 880 - 4, ROW, C.WASH) + g.rect(976 + 2, yy, 24, ROW, GOLD) + g.path(f"M{976 + 20},{yy + 12} l-10,-6 v12 Z", fill=gen.INK) + if line is not None and line != last_line: + again = line in seen + if line == cur_line and on: + g.rect(64 + 2, yy, 50, ROW, GOLD) + g.t(64 + 46, b(yy), str(line), S, gen.INK, BOLD, "end") + else: + g.t(64 + 46, b(yy), str(line), S, FAINT, MONO, "end") + text = D.SRC[line - 1] + C.c_line(g, 64 + 64, yy, text, 66) if not again else g.t(64 + 64, b(yy), text.strip(), S, FAINT, MONO) + seen.add(line) + elif line is None and (i == 0 or rows[i - 1][1] != func): + g.t(64 + 64, b(yy), "%s · no line" % func, 18, FAINT, "sans") + last_line = line + C.addr(g, 976 + 40, yy, a, CODE, lead=lead) + x = 976 + 40 + 8 * A + 12 + if bytes_: + g.t(x, b(yy), BYTES.get(a, ""), S, BRIGHT if on else DIM, MONO) + x += 15 * A + g.t(x, b(yy), mn, S, FAINT if mn == "nop" else KW, MONO if mn == "nop" else BOLD) + C.operands(g, x + 7 * A, yy, mn, ops, VELLUM) + if on: + C.chain(g, 976 + 600, yy, [(0x1004098, HEAP), (0x1004070, HEAP)], ("int", 9), {0: "read"} if False else None, + room=976 + 868) + return y0 + + +def frame_code(name): + """The code chapter: the source and its instructions side by side, each line level with its code, and the + instruction's bytes between the address and the mnemonic: an instruction is bytes too.""" + gen.W, gen.H = 1920, 1080 + g = Svg() + aligned(g, 48, 0x1001910, 16, 0x1001926, 21, bytes_=True) + gen.caption(g, [[("48 8b 7f 08", "mono"), (" is one instruction: ",), ("mov rdi, [rdi + 8]", "mono"), (", line 21's",)], + [("head->next", "mono"), (". The line sits level with its code: they are one row.",)]]) + g.save(name) + + +def frame_aligned(name): + """Mock 33: the `aligned` split, reverse and list_done, the pc at the load.""" + gen.W, gen.H = 1920, 1080 + g = Svg() + aligned(g, 48, 0x1001910, 30, 0x1001926, 21) + gen.caption(g, [[("Line 20, ",), ("while (head)", "mono"), (", has two runs: its test before the body",)], + [("and again after it. Lines 23 to 25 have no code of their own.",)]]) + g.save(name) + + +if __name__ == "__main__": + frame_bytes("29-intro-bytes") + frame_words("30-intro-words") + frame_stack("31-intro-stack") + frame_code("32-intro-code") + frame_aligned("33-aligned") diff --git a/design/motion.md b/design/motion.md index da903ab..bc58c6f 100644 --- a/design/motion.md +++ b/design/motion.md @@ -1238,6 +1238,60 @@ fault: the signal, rip and rsp at it, the exit status. And for the pair: the two recordings' stops matched by source line and by the loop's turn (i from its slot), so a step can be one line or one turn in both. +## A scene: the introduction + +The frame built from its bytes up, on the recording mocks 9 to 21 use +(`targets/list`, stopped at the load in `reverse`). Three short scenes, +not one: each is a chapter with its own opening and its own last picture, +which the next opens from, so a viewer can stop between them; together +104 s. Each view grows out of the rawer thing under it, in the order the +direction rule gives: memory first (the deepest), then the stack that is +made of it, then the code that acts on it, and the idea last, at the top. +Nothing cuts to a finished panel: the same bytes become the word, the +same word the row, the same row the slot. + +**Where the parts are.** Each part is built in the place it has in the +finished frame, never centred and moved later; the camera frames the part +being built (x2 for the first bytes, x1.5 for the words and the address +space, x1.25 for the stack and registers), so the frame's empty parts are +out of shot until the parts that fill them come. An introduction earns +that emptiness; nothing else does. A panel's tag and rule come last +(`frame up`): first the rows, then what they are called. + +**I. Memory** (43.9 s) + +| Lands | Leaves | Caption | Step, at | What plays | +| --- | --- | --- | --- | --- | +| 78 | 474 | A running program is bytes in memory. These are 128 of them, at the top of the stack. | 198 | the bytes fade in a row at a time (12 f, 2 f apart), no ink, the addresses faint; the camera at x2 (mock 29) | +| 492 | 852 | Eight bytes make a word, stored low byte first: read right to left. | 552 | `regroup` on the first word, walked; the other fifteen at a run | +| 870 | 1219 | Some words are addresses: numbers that name a place in this same memory. | 930 | one word framed as read, `10018b0` | +| 1237 | 1665 | The places are the program's mappings: its code, its data, the heap, the libraries, the stack. | 1297 | `segments` builds beside the words, a row at a time, top down; the camera out to x1.5 | +| 1683 | 2115 | A word takes the ink of the mapping it points into. That is where every colour here comes from. | 1743 | `ink`, word by word, 2 f apart, each with its mapping framed (mock 30) | +| 2133 | 2511 | Follow an address and you reach another word: the arrow, and the chain it makes. | 2193 | three words grow their chains (`extend`), walked | + +**II. The stack** (27.7 s), opening on I's last picture + +| Lands | Leaves | Caption | Step, at | What plays | +| --- | --- | --- | --- | --- | +| 78 | 478 | rsp holds the address of the top of the stack, this word. A push moves it down a word. | 198 | rsp's row arrives above, its pin lands on the top word; from the recording by instruction, the `push rbp` of `reverse`'s prologue replayed: rsp struck, the window sliding a slot | +| 496 | 791 | A call pushes the address to come back to: here, main+80. | 556 | the word `10018b0 main+80` framed; the offsets (`column`) | +| 809 | 1198 | A function's words are its frame: the caller's rbp saved, its locals, the way back. | 869 | roles (`column`), the spans, the rbp pin; the stack's tag (`frame up`) | +| 1216 | 1540 | The registers are the other place values live: seventeen of them. | 1276 | the registers built a row at a time over the stack, top down, then their tag, its legend the inks of I (mock 31) | + +**III. Code and meaning** (32.1 s) + +| Lands | Leaves | Caption | Step, at | What plays | +| --- | --- | --- | --- | --- | +| 78 | 378 | Code is bytes too. 48 8b 7f 08 is one instruction. | 198 | the code's bytes as a dump row in code's ink; one instruction's bytes framed | +| 396 | 796 | Decoded: mov rdi, [rdi + 8]. It came from line 21: each line sits level with its code. | 456 | `decode`, the instruction walked and its neighbours at a run; the source's lines arrive level with their runs: `aligned` (mock 32) | +| 814 | 1160 | rdi pointed at a list node on the heap. Its bytes, and drawn, the node. | 874 | `stack`: the aligned columns become the program column; the heap's dump arrives in the band's right half, then the nodes drawn from it (`establish`) | +| 1178 | 1491 | This is the whole frame. Every view in it is these same bytes. | 1238 | the camera out to x1; the minimap draws itself last: the working frame of mock 9, assembled | +| 1509 | 1809 | And all of it at once: the map. | 1569 | `surface` | + +Every caption is up its reading time and at most 450 f, leads its step +by 60 f (120 for a chapter's first), and changes only in a rest. The +rests are the chapters' ends: 2 s on each last picture. + ## Stills Seen while looking at motion; against `README.md`. -- cgit v1.3