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