diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 23:25:40 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 23:34:16 -0300 |
| commit | 2a97030c9743d4680d698414c28e8d8739614215 (patch) | |
| tree | 8415bb3aeeb5d5d909a2d311c2a30ab07f91c9fa /design/motion.md | |
| parent | 58643dab07a803dbb579d84f68419911f5a2a16d (diff) | |
| download | computeranim-2a97030c9743d4680d698414c28e8d8739614215.tar.gz computeranim-2a97030c9743d4680d698414c28e8d8739614215.zip | |
design: down is deeper; a call followed down; operands without size words; the heap as a scene
From the user. Direction and nearness are rules: the idea, the source,
its instructions, the callee and the kernel go down the frame, a call
goes down and a return comes up, and every tie runs one of those ways.
The disassembly can descend: a window a call depth, the caller keeping
three rows with its call waiting, a PLT stub its jump, the kernel at the
bottom on vellum, with verbs descend, cross and ascend. The kernel leaves
the band, which keeps the calls so far as strace writes them; the
backtrace has its newest frame at the bottom. Size words are dropped
from operands and a width is shown as byte cells where nothing else says
it; a compare shows its values and flags, a jump the flags it reads, an
indirect call its target and the slot it was read from. libc's heap is a
scene of blocks that exist (a dump by fields with a size and a protected
pointer read, arcs as the free list, a loupe into the tcache, the list
drawn over malloc's own), storyboarded on glibc 2.44. Mocks 16 to 18.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'design/motion.md')
| -rw-r--r-- | design/motion.md | 227 |
1 files changed, 199 insertions, 28 deletions
diff --git a/design/motion.md b/design/motion.md index 56a35bc..16a3e28 100644 --- a/design/motion.md +++ b/design/motion.md @@ -52,6 +52,10 @@ differently now: panel whole, and in the working frame's corner the minimap. A scene goes between them by `dive` and `surface` (below, "The map and the working frame"). +- Down is deeper: a call the narration follows opens its callee's window + under the call row and the kernel's under a `syscall` (the + [descent](README.md#descent)); the answer comes back up the same lane. + The backtrace lists the newest at the bottom. - `current` is a white wash across the row and the gold plaque; a strike's paper is a softened vermilion, and cools to nothing; `held` is a turned corner, which fades in over the cool's last 6 f. @@ -476,40 +480,81 @@ The trail shifts without animation. ### A system call -`read(3, buf, 32)`. The kernel's side holds the last call until this one -arrives. +`openat(AT_FDCWD, "note", O_RDONLY)`, followed down to libc's `syscall` +row ([`descent`](README.md#descent)). The kernel is under the program: its +window opens under the row, at the floor of the descent. Stepped over +(a line that calls the wrapper, not followed down), the same window opens +under the call row instead. | Frames | | | --- | --- | -| 0 to 12 | fire on the line | -| 18, 24, 30, 36 | `rax`, `rdi`, `rsi`, `rdx` framed as read, 6 f each: those that hold the argument at the stop shown, and no other | -| 48 to 72 | the crossing arrow draws down from the registers through the line, `standard` | -| 60 to 72 | the last call's name and rows fade out, `exit` | -| 72 to 84 | this call's name fades in, rising 8 units | -| 84, 90, 96 | its rows, top to bottom, 6 f each; `returns` shows a dash | -| 102 to 120 | its card pushes on the kernel's list | -| 120 to 144 | a flow draws from the kernel up to `buf` | -| 144 to 176 | the 16 bytes strike 2 f apart; no pulse | -| 180 to 186 | the `returns` row takes the value: the kernel answers before the answer travels | -| 186 to 210 | the arrow back draws up | -| 198 to 210, 210 | arm, strike: `rax`, as the arrow lands | -| 216, 222, … | the other registers the step changed (those the call clobbers, rcx and r11; those the wrapper restored), 6 f apart; then pins and links | -| 222 to 234, 234 | arm, strike: the word the line stores the result in (`n = read(…)`), when it does, after the registers | -| 234 to 270 | hold | -| 270 to 282 | advance | -| 282 to 306 | rest | +| 0 to 12 | fire on the `syscall` row | +| 18, 24, 30, 36 | `rax`, `rdi`, `rsi`, `rdx` (and `r10`, `r8`, `r9` as the call has them) framed as read, 6 f each, the argument rows hanging under the `syscall` row with them (`echo`): only those that hold the argument at the stop shown | +| 48 to 72 | the crossing lane draws down from the plaque, 3 units, vellum, `standard` | +| 66 to 78 | the kernel's window opens where it lands, the vellum filling down from the lane's head | +| 78, 84 | its head, then the call in C's form, each fading in over 6 f | +| 120 to 144 | a call with work: a flow draws from the kernel's window up the gutter to `buf` in the view (`read`; for `write` the bytes are framed as read first and the flow goes down) | +| 144 to 176 | the bytes strike 2 f apart; no pulse | +| 180 to 186 | `returns` takes the value, struck: the kernel answers before the answer travels | +| 186 to 210 | the answer climbs the lane to the `syscall` row | +| 198 to 210, 210 | arm, strike: `rax`, as it lands | +| 216, 222 | the registers the call clobbers, `rcx` and `r11`, 6 f apart; the band's log takes its new row (12 f, secondary) | +| 222 to 258 | hold | +| 258 to 270 | advance: the kernel's window draws back up into the lane (12 f) and the lane into the plaque as the plaque moves on | +| 270 to 294 | rest | The result is stored only after the kernel has given it: `returns` has -the value before rax, and rax before the local, never the other way -round. A step that makes more than one call (a continue through a -library) is not a crossing: the kernel's list takes the calls, oldest -first, 2 f apart, the newest decoded, and the step is a `continue`. +the value before rax, and rax before anything the caller does with it, +never the other way round. A call with no work (`open`, `close`) goes from +84 straight to `returns` at 108 and is 3.6 s; one that moves bytes, 4.9 s. +A step that makes more than one call (a continue through a library) is +not a crossing: the log takes the calls, oldest first, 2 f apart, and the +step is a `continue`. Nothing on the kernel's side changes before frame +66: the kernel does not know the call until it has crossed. -For `write` the work runs the other way: the user's bytes framed as read -(120 to 126), a flow down (126 to 150), the kernel's cells filling 2 f -apart. A call with no work (`close`) goes from 120 straight to the arrow -back: 3.7 s. Nothing on the kernel's side changes before frame 60: the -kernel does not know the call until it has crossed. +### A call followed down + +`call open@plt`, followed into the stub and on to libc's `open` +([mock 16](mock/16-descent.png)). Its first 60 frames are any call's. + +| Frames | | +| --- | --- | +| 0 to 12 | fire on the call row | +| 12 to 24, 24 | arm, strike: `rsp`. Its pin stays on the window's top row | +| 30 to 48 | the stack's rows slide down one slot, `glide` | +| 48 to 60, 60 | arm, strike: the return address, `main+48` | +| 66 to 78 | the caller's window closes round its call row: the rows it gives up fade out | +| 72 to 84 | the call row's gold plaque becomes the waiting ring, and the remaining three rows glide to the window's top (18 f to 90) | +| 84 to 102 | the call lane draws down from the ring, head first, `standard` | +| 96 to 108 | the callee's head fades in rising 8 units as the lane reaches it | +| 102 to 126 | its rows fade in top down, 2 f apart, 12 f each | +| 126 to 138 | the advance: the plaque lands on the callee's first row; the source's line goes `waiting` (6 f) where the callee has no source | +| 138 to 162 | rest | + +The stub's `jmp`, the next step, reads its GOT slot: fire (0 to 12); the +slot framed as read in memory, on the map or in a loupe, and the row's +annotation names it (18 to 24); the stub's window shrinks to that row, +`pass` (24 to 42, `glide`); the lane runs on from it to `open`'s head (42 +to 60); `open`'s head and rows come in as above (54 to 84); advance (84 +to 96). A jump is not a call: nothing is pushed. + +**Back up.** `open`'s `ret`: + +| Frames | | +| --- | --- | +| 0 to 12 | fire on `ret` | +| 18 to 24 | the return address framed as read on the stack | +| 24 to 36, 36 | arm, strike: `rsp` | +| 48 to 72 | `open`'s window closes, its rows fading bottom up, 2 f apart, 12 f each, its head last; the stub's `pass` row with it: the return skips the stub | +| 72 to 84 | the lane draws back up into the ring | +| 84 to 102 | main's window grows back to the panel, `glide`; the rows it gave up fade in | +| 102 to 114 | the ring becomes a trail bar, the call's annotation takes its result (`= 3`, 6 f), and the plaque lands on the row after the call; the source's line from `waiting` to `current` | +| 114 to 138 | rest | + +A descent is a beat the narration names, and each of its steps is walked: +at a run the windows open and close in 8 f with no lane drawn, and at a +sprint the scene surfaces to the map, where the disassembly column is the +descent whole. ### A continue @@ -849,6 +894,132 @@ In each, most valuable first. Times are seconds into the exported file. 8. Text under the zoom is steady ([sheet](motion/sheets/zoom-05.1-text-settles.png)): nothing to do. +## A scene: libc's heap from the inside + +Not a lens: a scene, drawn with the blocks the catalogue has, and two +small additions (`nodes` in two rows with a `bin` at the second's head, +and malloc's words `size` and `protected` in a dump). The program is +[`mock/heap.c`](mock/heap.c): three pushes, two pops, a push. Every byte +below is a recording's: `ztrace dbg` on it under glibc 2.44, stopped after +each `malloc` and `free` returns ([mock 18](mock/18-heap.png)). + +**The frame.** Split `subject`. The band's drawing is `nodes` in two rows: +the program's list from `head` over the tcache's free list for chunks of +0x20, headed by its `bin`. Its view is the heap by `fields`, seven rows, +405000 to 40506f, three chunks of two rows each and the next chunk's +header: each size word read as `size` (`0x20 a m P`), a node's two words +as the program's (`number`, `pointer`) while it has them and as malloc's +(`protected`, then `bytes` noted `key`) while malloc does. Both lists are +`arc`s in the view: the program's `next`s, and the free list's links to +the pointers they protect. The tcache is a `loupe` hung from the view's +row of the chunk it lives in (405060), two of its rows named: +`num_slots[0]` and `entries[0]`. The disassembly is the program's; the +calls to `malloc` and `free` are stepped over (free's own path is two +hundred instructions: a descent into it is a scene of its own). + +**The map and the minimap.** The map's memory column holds the heap +whole, from its start to the top's header (rows round what was touched, +fieldless ones folded), the tcache as its own panel under it, and the +arena (`main_arena`, in libc's data, far from the heap) as a dump by +fields: `top`, `last_remainder`, `system_mem`, `flags`, and the bins' +heads. On the minimap those three are where they sit; a strike on one no +window shows (the top's header moving down when the tcache is cut from +it) flashes there. + +**The beats.** + +| | Stop | Caption | What plays | +| --- | --- | --- | --- | +| 1 | the first `malloc` returns | malloc(16) cut a chunk of 0x20 off the top: its size word, 0x21, then the 16 bytes rax points at. The top is 0x20 smaller. | `fire`; `rax` struck and its `link` to the pin under a node that fades in on the program's row (12 f); the view's rows come in unmarked, the region being new (a dump that comes in after its step has no marks); the `bin` dashed, `dummy tcache`: before the first free the thread's tcache is a read-only dummy in libc | +| 2 | after `push(9)` | Three pushes, three chunks in a row, each with P: the chunk before it is in use. The list's next pointers are arcs in the bytes. | the second and third pushes at a run (8 f eases), each `next` written struck and its `arc` drawn (12 f), quieting with the cool; `head`'s pin travels to the newest node (30 f) | +| 3 | the first `free` returns | free gave 9's chunk to the tcache, malloc's bin for 0x20. Its first word is the link now: 405, which is NULL, safe-linked. | the chart below: the tcache made, the loupe opened on it, the node travelling down to the bin's row | +| 4 | the second `free` returns | The second chains to the first: 405455 is 405050 xor 405, the chunk's own address shifted 12. The arc is the pointer it hides. | the same, shorter: the chunk's first word struck (`55 54 40`) and its key; in the loupe `entries[0]` struck on its low byte alone (`50` to `30`) and `num_slots[0]` 15 to 14; the free node glides one place right (18 f) and the new one lands at the bin's head; the `arc` from 405030 to 405050 draws at full ink (12 f); the count 1 to 2 | +| 5 | the next `malloc` returns | malloc(16) took the bin's head, 405030: the tcache points at 405050 again, the key is wiped, and the old link stays until push writes. | `rax` struck and its link to the node; the key's 8 bytes struck to zero; the loupe's head and count struck back; the arc from 405030 fades (the word is the program's again, read as `bytes`, `the old link`); the node travels up to the program's row (36 f) and its halves turn back, the old link faint in the value's half; the count 2 to 1. Then `push` writes 25 and its `next`, and that arc draws | + +The first free, frame by frame: + +| Frames | | +| --- | --- | +| 0 to 12 | fire on `free(n);` | +| 18 to 30 | the registers `free` left changed, struck in a wave 2 f apart (`rax`, `rcx` 405, `rdx`, `rsi` the key, `r8`, `r10`): it was stepped over, so as a `continue` | +| 54 to 66, 66 | memory: the chunk's first word armed and struck, its two bytes that changed 1 f apart (`05 04`) | +| 72 to 80 | its second word, the key, 8 bytes 1 f apart | +| 90 to 102 | the next chunk's header struck (`01 03`): the tcache's chunk, cut from the top at this first free; the top's own header has left the window, and flashes on the minimap | +| 102 to 138 | `open`: the loupe on the tcache, hung from that row: the row framed as read, the stem, the rise, its two fields framed | +| 144, 150 | in the loupe: `num_slots[0]` struck (16 to 15), then `entries[0]` (`50 50 40`) | +| 162 to 174 | the idea: the `bin`'s box goes from dashed to raised, `tcache 0x20` | +| 168 to 210 | the node lifts (6 f) and travels down to the bin's row (36 f, `glide`); as it lands its outline goes dashed and its halves turn (12 f): the first word's half the link's well, the second hatched, `key`. `rdi`'s pin rides with it: the pointer was freed, not cleared | +| 210 to 222 | the count lands on the bin's shoulder, struck: 1 | +| 222 to 258 | hold | +| 258 to 270 | advance | +| 270 to 294 | rest: 4.9 s | + +The loupe stays open while the caption names the tcache (beats 3 to 5), +each of its changes a strike in it; it closes with the advance after beat +5's push. + +**What the scene's author writes.** A sketch in the shape of +`anim/scenes/sqlite.zig`'s fields: + +```zig +// The view: a chunk as the program has it, and as malloc does. +const used = [_]Field{ + .{ .at = 8, .len = 8, .reads = .size }, // size, A M P + .{ .at = 16, .len = 8, .mark = 0 }, // value + .{ .at = 24, .len = 8, .reads = .pointer, .mark = 1 }, // next: an arc +}; +const freed = [_]Field{ + .{ .at = 8, .len = 8, .reads = .size }, + .{ .at = 16, .len = 8, .reads = .protected, .mark = 2 }, // the tcache's next: an arc + .{ .at = 24, .len = 8, .reads = .bytes, .note = "key" }, +}; +// Which a chunk gets is the recording's: the list each chunk is on, per stop. +// The tcache, as a loupe from the row of its chunk: two fields of 760 bytes. +const tcache = [_]Field{ + .{ .at = 0, .len = 2, .note = "slots left" }, // num_slots[0] + .{ .at = 0x98, .len = 8, .reads = .pointer, .note = "the head of 0x20" }, // entries[0] +}; +// The drawing: the list from `head`; the bin `tcache 0x20`, its count the +// reader's (16 less the slots left), its chain the reader's, revealed. +``` + +**What the recording must hold, per stop.** The tracer's reader +(`zt.heap.glibc`) has most of it; the scene needs: + +1. The chunks in address order, each with its address, its size word + (at address + 8) and the list it is on (in use, tcache and which, + unsorted, small or large and which, the top). +2. For each chunk on a list, its two link words as stored and the pointers + they protect, and how each chain ends (the end, memory not recorded, + misaligned, a limit). +3. The tcache whole: its address, `num_slots` and `entries` (76 each on + 2.44), and the capacity a bin starts with (16 here), so the count shown + is what the bin holds. Before the first free, the thread's `tcache` + pointer, at libc's dummy. +4. The arena: its address, `top`, `last_remainder`, `system_mem`, + `flags`, and the bins' heads, each with its word's address. +5. The bodies of the in-use chunks the scene draws: the reader records + them only when watched, so the heap's first kilobyte watched (`-w` + on it) or `--around` round what each instruction touches. +6. Which bytes changed since the stop before (a pointer whose low byte + alone moved is struck on that byte), and glibc's version: 2.44 makes + the tcache at the first free, counts slots left, and has no fastbins. + +**Further beats on this glibc**, with the same blocks: a large chunk +freed beside a live one goes to the unsorted bin (a third row, its `bin` +the arena's bin, the chain ending `→ the bin`; the next chunk's `P` chip +struck clear); a malloc that sorts it into a large bin (the node travels +between rows); a chunk freed beside the top merges into it (the node fades +into the top's box, whose size is struck). Fastbins only as a beat marked +`glibc before 2.41`, under the 2.40 that runs through pwndbg's loader. + +**musl's mallocng** would keep the dump by fields (a group's header and +its slots), the arcs (meta to group and back), a loupe on the meta (its +`avail_mask` and `freed_mask` read as bits, as `size` reads A M P), and +the per-class rows; but its free list is a bitmask in metadata kept +apart from the chunks, not links inside them, so its drawing is a row of +slots, nearer `array` than `nodes`, with no safe-linking to show. + ## Stills Seen while looking at motion; against `README.md`. |
