diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-11 11:27:09 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-11 11:51:02 -0300 |
| commit | beb2616a243e01826c3103209d5525381a5da73d (patch) | |
| tree | 195c30132791de8ed1bed0461ce2825bdfbfe819 /design/README.md | |
| parent | dcbe8941df205fa8c8805b022f025e1012dede19 (diff) | |
| download | computeranim-beb2616a243e01826c3103209d5525381a5da73d.tar.gz computeranim-beb2616a243e01826c3103209d5525381a5da73d.zip | |
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 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
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 |
