summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md70
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