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/README.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/README.md')
| -rw-r--r-- | design/README.md | 505 |
1 files changed, 384 insertions, 121 deletions
diff --git a/design/README.md b/design/README.md index a6cc6dd..e465e8e 100644 --- a/design/README.md +++ b/design/README.md @@ -37,6 +37,12 @@ scene that draws every block in every state is the test of this page. and a moment. 8. **Low level first.** The bytes change, the tie carries it, the drawing reacts. A cause is always on screen before its effect. +9. **Down is deeper, and what acts together sits together.** The idea + over the source, a line over its instructions, a call over its callee, + the program over the kernel. Execution goes down and across; what it + means comes back up. A pointer and its target, a call and its callee, a + drawing and its bytes are neighbours + ([direction and nearness](#direction-and-nearness)). ## Vocabulary @@ -55,23 +61,24 @@ this table. | | [`pin`](#pin) | a register's or a variable's name at the thing it points to | `row`, `under` | | | [`bracket`](#bracket) | a span marked at its edge | `quiet`, `tie` | | | [`tag`](#tag) | a panel's title bar | `focus`; `note` or `legend` | +| | [`width`](#width) | an access's size in byte cells, where no register says it | 1, 2, 4, 8 cells; a count past 8 | | 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop; opens a `loupe` | | | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) | | | [`slot`](#slot) | a word of the stack and its chain | pins; `free` | -| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` | -| | [`line`](#line) | a line of source | `current`, `trail`; wide numbers | -| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run; wide address | +| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside`, `waiting`, `pass` | +| | [`line`](#line) | a line of source | `current`, `trail`, `waiting`; wide numbers | +| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs (`size`, `protected` among them), marks per byte; wide address | | | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` | | | [`arc`](#arc) | a pointer to a row of the same panel, drawn | standing, `touched`; a stub | | 3 panel | [`registers`](#registers) | all seventeen | | | | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | 8 or 6 slots | -| | [`backtrace`](#backtrace) | the call chain as rows | in the `none` split; the view of `calls`; a lens's drawing | +| | [`backtrace`](#backtrace) | the call chain as rows, newest at the bottom | in the `none` split; the view of `calls`; a lens's drawing | | | [`source`](#source) | a window on the file | 14, 8 or 10 lines | -| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows | +| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows; a [`descent`](#descent): a window a call deep, the kernel at the floor | | | [`lens`](#lenses) | a drawing of some state over the program's two columns, and in the third the pane it is a view of | `beside`, `subject` | | | [`hexdump`](#hexdump) | memory, a `bytes` row a line | typed or by `fields`; `more` rows; `seen`; `given`; `memory` | | | [`loupe`](#loupe) | the memory round a pointer's target, floating over the context | two at most, in depth | -| | [`nodes`](#nodes) [`array`](#array) [`calls`](#calls) `heap` `syscalls` `pages` | the drawings a lens can hold | | +| | [`nodes`](#nodes) [`array`](#array) [`calls`](#calls) [`syscalls`](#syscalls) `pages` | the drawings a lens can hold | `nodes` in two rows, a `bin` heading the second | | 4 tie | [`thread`](#4-ties) | the current line is these instructions | standing | | | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin`; a stub when that is out of view | | | [`projection`](#4-ties) | these bytes are that part of the drawing | for a step | @@ -85,6 +92,7 @@ this table. | | [`card`](#clock-and-caption) | a title, the legend: no program running | | | 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 | | | | [`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 | | @@ -247,6 +255,7 @@ Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth. | --- | --- | --- | | `number`: a field read as a number, or left to the eye | primary | raised, one rect a field | | `pointer`: a field that is one | the region it points into | raised, one rect a field | +| `size`, `protected`: malloc's words, read as below | primary: what is stored is not where it points | raised, one rect a field | | `text`: a field read as text | a string's | raised, one rect a field | | `loose`: a byte of no field: the allocator's between allocations, a struct's padding, what lies past the thing the dump is of | dim | none | | `unread`: not observed at the stop shown | two 4-unit squares, faint | none | @@ -352,6 +361,31 @@ serifs 6 or 7, in the ink of the tie it ends. primary under focus and dim otherwise. Ranged right, a `note` (Go 18, faint) or a `legend` (words in Go Medium 18, each in its ink, 14 apart). +### width + +How many bytes a memory access touches, drawn as that many byte cells, +where nothing else in the instruction says it. It replaces the +disassembler's size words (`byte ptr`, `dword ptr`, `qword ptr`), which +are dropped from every operand ([`insn`](#insn)). + +- **Form.** Cells 5 wide and 10 high, 7 apart, in `dim`, standing on the + baseline 3 after the operand's `]`; what follows the operand goes on 4 + after the last cell: `[rbp - 0x60]▮▮▮▮, 0x10`. One cell for a byte, two + for a word, four, eight. Wider (`tbyte`, `xmmword` and up): eight cells + and the count in faint mono 20. +- **When.** Only where no register outside the brackets of the same + instruction has the access's size, and the mnemonic does not fix it: + `cmp [rip + 0x11018b]▮, 0` (an immediate), `mov [rbp - 0x60]▮▮▮▮, + 0x10`, `movsxd r10, [rbp - 0x30]▮▮▮▮` (the register is 8, the read 4). + Not on `mov rdi, [rdi + 8]`, `mov [rbp - 0x38], eax`, `push`, `pop`, a + `call` or `jmp` through memory (always 8), `lea` and the padding `nop`s + (they touch nothing). +- **Why cells.** A numeral under mono 20 breaks the floor; a suffix on the + mnemonic (`movl`) is a second syntax. A byte is already a cell in every + dump, so four cells read as four bytes. + +Mock 17. + ## 2. Rows Every row is 24 high and one line. None wraps; what does not fit is cut at @@ -415,19 +449,23 @@ An instruction, pwndbg's way: what it is, and what its operands are now. | 31 | jump lane | a 2-unit line in trail gold from a jump that was taken to the row it landed on, head 7 by 8 | | 40 | address | code ink, `lead` | | 134 | line | the source line this run of instructions came from, ranged right in three characters, faint; on the first row of each run only; gold and bold for the current line. Wide numbers (see [`line`](#line)) widen it, and every column right of it moves by the extra: mnemonic, operands and annotation, the row's room 12 characters less for six digits | -| 180 | mnemonic | keyword, bold | -| 264 | operands | as the disassembler writes them, whole; a jump's or call's target is an `address` in code ink | +| 180 | mnemonic | keyword, bold; `nop` and `endbr64` faint, with their operands: padding, which touches nothing | +| 264 | operands | as the disassembler writes them, whole, less the size words (`qword ptr `): a [`width`](#width) after the bracket where no register says the size. A jump's or call's target is an `address` in code ink; a PLT stub's, named by the stub: `401070 open@plt` | | 564 | annotation | from 564, or a character after operands that run past it; a chain, cut at its far end by the chain's rule | +**Wide addresses.** An address of more than seven digits (a library's +twelve, `7ffff7d10fc5`) moves every column right of it by the extra, 12 a +digit: in libc the mnemonic is at 240, the annotation at 624. The width is +the window's own: in a [`descent`](#descent) the caller's window does not +move when libc's opens under it. + **Room.** The row holds 50 characters from 264, to 12 from the panel's edge. Operands are never cut where the row has room, and never inside `[]`: we do not hide what the instruction says. When the operands and the whole annotation do not fit, in this order: 1. the annotation moves left to where it just fits, never left of 564; -2. a size word (`qword ptr `) goes from a memory operand whose size a - register operand gives: `mov rax, [rbp - 0x28]`. Nothing is lost; -3. the operands give way to the annotation: they end where it begins, in +2. the operands give way to the annotation: they end where it begins, in a faint `…`. A cut that would fall inside `[]` falls before the `[`, and the annotation's first hop is the address the brackets named. @@ -437,6 +475,8 @@ whole annotation do not fit, in this order: | `ran` | trail bar, newest of three brightest; keeps the annotation of what it did | | `ahead` | plain; only static annotation (a callee's name) | | `outside` | another function's: plain, as `ahead`; over its first row a rule, and its name in that row's annotation column, dim. Past the program's text (padding, a section's end): faint | +| `waiting` | a call whose callee's window is open under it, in a descent: the plaque's place ringed (a 2-unit primary frame 24 by 24, a primary head in it), as a waiting call node is; no wash. Its annotation is the call in C's form: `open("note", O_RDONLY)` | +| `pass` | a stub's jump, gone through on the way down: a trail bar; the call lane runs on from it | **The annotation**, by what the instruction does: @@ -445,22 +485,33 @@ whole annotation do not fit, in this order: | reads memory | a chain from the address it computes: `28b41098 → 28b41070 ◂ 9`. Before the step, where it will look; in the step its first hop is `read` | | writes memory | the same chain; the value after `holds` is `struck` | | only sets a register | a small `reg`: `rax 28b41090 ◂ 4` | -| jumps on a condition | `taken` in primary, or `not taken` in dim; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37` | -| calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there | +| compares or tests | the two values it compares, ` : ` between, faint: `3 : -4096`; then the flags it leaves, those the conditional after it reads (CF ZF SF OF when none follows): set on a chip as rip's are, clear in dim lower case: `3 : -4096 CF zf` | +| jumps on a condition | `taken` in primary, or `not taken` in dim, then `· reads` and the flags it reads, as the compare drew them; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37`. While it is current, the chips on the row that set them are framed as read with it (an `echo`), and rip's | +| computes an address (`lea`) | `=` and what it made: an address and its chain (`= 402004 "note"`), or a number. With room, the sum first, each register's value in its ink: `rbp 7fffffffed00 - 0x30 = 7fffffffecd0` | +| calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there. Through a PLT stub: the function the stub reaches, `open` (or `the resolver` while its GOT slot is still lazy). Once it has run: the call in C's form and its result, `open("note", O_RDONLY) = 3` | +| calls or jumps through memory or a register | where it goes: `→ 7ffff7d10ec0 open`; then, faint, where that was read: `· read from open@got, 403fd8`. Out of room, the slot goes first, then the target's digits; its name stays: `→ __pwrite64` | +| reads a place the C library's layout names | the name, then the value: `fs:[0x28]` is `the stack's canary 191a6a1f012bed00` | +| repeats (`rep stosq`, `rep movsb`) | the count and the step: `rcx 12 · 8 bytes each`, the destination's chain after. Stepped by instruction a `rep` stays current while rcx counts down, an iteration a step | | returns | `→ 10018b0 main+80` | -| makes a system call | its name and arguments by name, as a call; the kernel's rows hang under it on vellum | +| makes a system call | its name and number, `openat nr 257`; its arguments hang under it by name, as a call's; in a [`descent`](#descent) the kernel's window opens under its window | Mocks 9 to 11 show the read, the register-setter, the taken jump and `outside`; 12 a call with its argument, a write, and operands longer -than 24 characters with the annotation moved right of them. Return and -syscall annotations are not drawn. +than 24 characters with the annotation moved right of them; 14 an +indirect call by name; 16 a call through the PLT, `waiting`, `pass`, a +system call; 17 a compare and the conditionals reading it, a `lea`, a +named place. A `rep`, and the flags' echo, are not drawn. ### line The number ranged right in three characters, faint; the text from 64, in the four code inks; 67 characters, then a faint `…`. `current`: gold plaque on the number, the wash across. `trail`: the bar, for the last three -other lines run. +other lines run. `waiting`: the pc is in code with no source (libc, a PLT +stub, the vDSO) under this line's call: the number ringed, a 2-unit +primary frame where the plaque would be, no wash; the source's tag says +where the pc is (`main waits at line 6 · the pc is in libc's open`), and +the thread waits with it (primary, 2 units). **Wide numbers.** The number column is as wide as the program's largest line number, three characters at least: sqlite3.c's 262 899 lines take @@ -491,6 +542,23 @@ twelve put them at 190, and the reading at 698 (508 after the first byte, as always). A dump sets this once, by the widest address in its window, so its rows keep one column. +**Malloc's words**, for a scene about the allocator (elsewhere the size +word is the faint note above): + +- `size`: a chunk's size word. The reading is the size, the three low + bits cleared, in hex as malloc's sizes are read (`0x20`), then the bits + as rip's flags are drawn, `A M P` (not the main arena, mmapped, the + chunk before in use): set on a chip, clear in dim lower case: + `0x20 a m P`. A bit that changes is struck and held on its chip. +- `protected`: a pointer glibc stores safe-linked, the pointer xor its own + address shifted right by 12. The bytes are what is stored, in primary + (`55 54 40`); the reading is what they protect, `→ 405050`, or `NULL`, + then the mask, faint: `→ 405050 ^ 405`. Its [`arc`](#arc) goes to the + pointer it protects. A NULL so stored is not zero (`05 04`, 405), which + the reading says. +- A field may carry a note from the scene, Go 18 faint, after its reading + or as its reading: `key`, `slots left · 1 in the bin`, `the old link`. + The reading replaces a hexdump's text column: where bytes are text the reading is the text, in quotes; where they are a pointer it is the address, so a little-endian pointer is read without leaving the dump. It is a list, @@ -620,12 +688,16 @@ rsp+48`), and `· the frames they belong to`. ### backtrace -`call` rows, newest on top. A panel of its own in the `none` split, four +`call` rows, the oldest on top and the newest at the bottom: a call adds +a row under the others and a return takes it away, as the calls tree +grows down beside it. `#n` keeps gdb's numbering, `#0` the newest, gold. +A panel of its own in the `none` split, four and then a count, under the stack; the view panel of a [`calls`](#calls) lens, seven; the drawing of a [`backtrace` lens](#lenses), eleven as -subject and five beside; in the other splits the stack's spans carry it. -More frames than rows: the oldest go, and the tag's note counts them, -`newest on top · 2 more`. On the map it is whole. +subject and five beside, its `#0` just over the source line it is at; in +the other splits the stack's spans carry it. +More frames than rows: the oldest go from the top, and the tag's note +counts them, `newest at the bottom · 2 more above`. On the map it is whole. On a stop far from the last (a [`continue`](#6-verbs)) the chain changes as rows making room: the frames that end fade out (12 f); the frames both @@ -661,6 +733,55 @@ Nine (four, the pc, four) when the lens is the subject. On the map the column is 69 rows: the function whole when it fits, with its neighbours round it. +A call the narration does not follow moves the window to the callee, as +above: the stack's spans and the backtrace carry the depth. A call it +follows opens a descent. + +### descent + +The disassembly a level up: a call followed down. The panel becomes a +stack of windows, one a call deep, the caller's on top and each callee's +under the row that called it, and under the deepest, while a system call +is made, the kernel. Down is deeper, and the way back up is drawn. + +| Part | Drawn | +| --- | --- | +| a caller's window | its call row, `waiting`, the row before it and the row it will return to: three rows. The nearest caller gets the rows the deepest does not use, round its call row | +| a head | a row: a 2-unit rule across, the callee's name at 40 (Go Medium 18, primary), what it is ranged right (Go 18, faint): `libc.so.6 · no source`, `the PLT · its jmp reads open@got, 403fd8`, `vdso · the kernel's code, run here` | +| the call lane | 2 units, primary, from the waiting ring at x 14 straight down to the head, turning in to a head 7 by 8 before the name. It is part of the panel, as the jump lane is, and not a tie of the budget | +| a stub | its rows whole (a PLT entry is three); once its `jmp` has gone on, its window keeps that row, `pass`, and the lane runs on from it to the next head | +| the deepest window | as long as it needs: a stub whole, else the rows round the pc as the panel's; four of its rows under a `syscall` hold the call's arguments | +| the kernel | the floor: solid vellum, its head `the kernel` and the call (`openat, system call 257`); the call in C's form; `returns` and the value (struck as it lands), with what the crossing clobbered (`rcx, r11`). The crossing lane: 3 units, vellum, from the `syscall` row's plaque down to the vellum, its head in ink on it | +| the panel's tag | the deepest function and its module: `open · libc.so.6` | + +In seventeen rows, the call to `open` at its `syscall`: main's three, the +stub's head and its `pass` row, the wrapper's head and eight rows, the +kernel's head and two rows ([mock 16](mock/16-descent.png)). + +- **Depth.** Three windows of code at most, and the kernel. A longer chain + keeps the first and the last two; the ones between are one row, `more`'s + arrow and `2 calls: fib fib`. The stack's spans and the backtrace hold + the whole chain. +- **The source** stays on the deepest frame that has source, its line + `waiting`, while the pc is in code without it. Into a function of the + program's own the source follows the pc as it always does; the call's + line is in its waiting row's annotation. +- **Any call.** The program's own function: its window, its lines. + libc's: no source, its symbol and module. A PLT stub: its three rows, + the GOT slot named in its head; under lazy binding its `jmp` goes back + into the PLT and to the loader's resolver, which is one row of `more` + (`→ … _dl_runtime_resolve, 412 instructions`), and the GOT slot it + writes is struck in memory, where the data is. The vDSO: its window, no + kernel under it (the point of it); what it reads is the `[vvar]` page. +- **Up.** A `ret` closes the windows under its caller's, bottom first; + the caller's window grows back to the panel and its call row is `ran`, + its annotation the call and its result. A stub jumped through closes + with the function it jumped to: the return goes straight to the caller. +- **On the map** the column is the descent whole: each window its + function, whole where it fits, the kernel's under the last. + +Its motion is [`descend`, `cross`, `ascend`](#6-verbs). + ### lenses A lens is the band across the top of the stage: **a drawing, over the @@ -674,10 +795,9 @@ the drawing keeps its subject size and the view is its region whole. | --- | --- | --- | --- | | `nodes` | boxes of a value and a pointer, arrows between them | a `hexdump` of the nodes' bytes | 9 to 11; 2 at camera scale | | `array` | cells, index pins, flights for a swap | a `hexdump` of the array's bytes, an element a run | 7 at camera scale | -| `heap` | the heap to scale: chunks, bins | a `hexdump` of the chunk in hand | 4 at camera scale | | `calls` | a call tree under its caller, results on the shoulder | the `backtrace`; each node is also a `call` span on the stack, tied by `project`. Subject only: a tree needs the height | 12; 1 at camera scale | | `backtrace` | the call chain itself, as `call` rows (eleven as subject): how the program came to be here, when that is the story and no one function's calls are | a `hexdump` by `fields` of what the newest call was handed (the struct an argument points at, a buffer), at its stop | 13, 14 | -| `syscalls` | the kernel's side, on vellum: the calls so far, the call decoded, the bytes it holds | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 3 at camera scale | +| `syscalls` | the calls so far, as strace writes them, oldest on top; the kernel's own side is the [`descent`](#descent)'s floor | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 14; 16; 3 at camera scale | | `pages` | the far view: pages, system calls over time | the mappings, a row each | 8 | | `hexdump` alone | bytes and their text | itself | 5, in its first-pass form | @@ -685,6 +805,12 @@ the drawing keeps its subject size and the view is its region whole. touch, each a `hexdump` kept round what was read or written, typed where the recording types it; a lens's view is a window onto it. +There is no heap lens. libc's heap is a scene drawn with these blocks: +`nodes` in two rows (the program's list over malloc's free list), its view +the chunks by `fields` (`size`, `protected`), the free list as `arc`s, a +`loupe` on the tcache ([the heap scene](motion.md#a-scene-libcs-heap-from-the-inside), +mock 18). + A scene may change its lens where it stands: the drawing fades out (12 f), then the next fades in (12 f) and its elements come in as at `establish`; a view the two share stays. The split does not move, so this @@ -714,6 +840,24 @@ dim slash. **Above** each node its address, in its region's ink: the same digits as its row in the dump. **Under** it, its pins. Marks on a half: `read` frames it, `held` is the bar along its bottom edge. +**Two rows**, for chunks that change hands (the heap scene): the +program's list on top, from its variable's pin, and under it the +allocator's free list, both in list order, 110 apart. A node goes from +one row to the other when it is freed or taken back (`travel`, 36 f). The +boxes are 136 wide, so a stale word can be read in the value's half. + +- A node the allocator holds is drawn `freed`: its outline dashed 12 on + 8, its first word's half the well and the link's square (glibc's tcache + keeps the link where the value was), the second half hatched with `key` + in faint. The arrow is the link as it protects, not as stored. +- **`bin`**, the second row's head: a raised box 160 by 44 at the row's + left, the bin's name in mono 20 (`tcache 0x20`), how many chunks it + holds on its shoulder as a call's result is (a square of 30, mono 25), + an arrow from its right edge to the first chunk. Before the bin exists, + the box dashed and faint (`dummy tcache`). The count is what the bin + holds, worked out from what glibc stores (2.44 stores the slots left, + 16 less it; the loupe on the tcache shows both). + ### hexdump `bytes` rows, sixteen a row, a window of the region kept round the rows @@ -732,7 +876,8 @@ Its runs come one of two ways. - **`fields`**: a region the scene names (a base, a length, the memory's region ink) and the fields it gives it, each `at` an offset, `len` bytes long, read as a `number` (low byte first, or `big`: high byte - first, as a file format stores it), a `pointer`, `text`, or `bytes`, + first, as a file format stores it), a `pointer`, `text`, malloc's + `size` or `protected` ([`bytes`](#bytes)), or `bytes`, left to the eye: on raised paper with no reading. A byte of no field is `loose`. A field is a run, cut where a row ends. This is how a real program's memory is drawn when the debug info does not type it, or the @@ -821,29 +966,35 @@ left out is counted, never dropped. ### syscalls -The kernel's side, on vellum (solid vellum is the kernel): the calls so -far, newest on top, each with what it returned; the call in hand, -decoded: its name, its arguments by name beside the registers the call -takes them in (`rdi fd 3 "t.db"`), `returns`; and the bytes it was given -or filled, ten a row, two rows. Its view is a [`hexdump`](#hexdump) by -`fields` of the buffer, `given`. +The program's conversation with the kernel. The drawing is the calls so +far as strace writes them, a row each, oldest on top and the newest at +the bottom: the name in bold, the arguments by name with their values +(`fd 3 "t.db"`, `buf 538b28`) where the recording has them, ` = ` and +the result, the newest's with the turned corner. Its view is a +[`hexdump`](#hexdump) by `fields` of the buffer, `given`. The band is not +the kernel and is not on vellum: the kernel is under the program, the +floor of a [`descent`](#descent), where the call is made. A crossing +stepped over (a line that calls libc's wrapper, not followed down) opens +the same window under the call row: the wrapper is not shown, and the +kernel is still under the program. A **crossing** is a step that makes one system call; its timetable is -[motion.md's](motion.md#a-system-call). What it may claim: +[`cross`](#6-verbs) and [motion.md's](motion.md#a-system-call). What it may claim: - A register is framed as carrying an argument only while it holds that argument at the stop shown. Stopped in the caller of libc's wrapper, `pwrite64`'s buffer and count are in rsi and rdx, but its descriptor is not yet in rdi nor its offset in r10: those two are not framed, though - the kernel's rows name them. -- Nothing on the kernel's side changes before the arrow down arrives. - `returns` takes the value before the arrow back leaves, rax is struck + the kernel's window names them. Followed down to the `syscall` row, + all of them are. +- Nothing on the kernel's side changes before the crossing lane reaches + it. `returns` takes the value before the answer leaves, rax is struck as it lands, and everything else the step changed (the registers the - wrapper and the call clobbered, pins, links, a result stored in memory) - waits for rax. + call clobbered, pins, links, a result stored in memory) waits for rax. + The log's row comes in with `returns`. - A step that makes several calls (a continue through a library) is not - a crossing: the list takes them, oldest first, 2 f apart, each fading - in; the newest is decoded; no arrow, no bytes. + a crossing: the log takes them, oldest first, 2 f apart, each fading + in; no lane, no kernel window, no bytes. ### loupe @@ -933,6 +1084,7 @@ projection): | a lens's bottom lane, 8 above its edge | what arrives from below: a link to the pin under its node; a projection to a call node | | a lens's top lane, 4 under its tag | a projection from the view, to the bracket over its node's address | | a panel's pin lane | a link's last leg to a `row` pin, or its stub | +| the disassembly's call lane, x 14 | a descent's call lane, down from a waiting row to its callee's head; the crossing, down to the kernel's window, and the kernel's answer back up it | | none | a loupe's stem: from its pointer straight to the loupe, over the row's empty end, or the gap between a loupe's row and the loupe it opens | Ties that climb from the state column take the left lane and arrive from @@ -995,6 +1147,76 @@ rest, and the minimap shows it. | lens band (the drawing and its view) | | 13% | 21% | | caption band, with the minimap | 10% | 10% | 10% | +### Direction and nearness + +**Which way things go.** + +- **Down is deeper.** Under each thing in the program column is what it + becomes: the idea (the band) over the source, a line over its + instructions, a call over its callee ([`descent`](#descent)), the + program over the kernel. In the state column the registers are over + the stack. A call goes down and a return comes up; in the backtrace and + the calls tree the newest is lowest. +- **Memory is where it is.** A dump, the stack and a loupe are in address + order, low on top, because a row's place there is its address: so the + stack's newest frame is its panel's top, and an arc or a jump's line goes + whichever way the addresses do. It is the one exception. +- **Execution goes down and across; meaning comes back up.** A step's + cause is a row of the program column. Its effects cross the gutter into + the state (an instruction to the register it writes) and go down it (a + register into the stack); what they mean climbs into the band (from the + stack up the gutter, from a register to a pin under a node) and crosses + back to the drawing from the bytes beside it. An answer comes back up + the way its call went down: a return to its call row, the kernel's answer + up the crossing lane to the `syscall` row, then rax. +- **A still is read the other way, top down**: what it means first, then + how it is made. The band is on top because the idea is what a scene is + about. +- **Every tie runs one of those ways.** In the context down or right (the + thread, a link to a slot, a loupe's stem, the call lane and the + crossing); into the band up, then left (a link to a pin, a projection). + None runs against them. + +**What sits together.** Things that act on each other are neighbours, +each pair in one place: + +| Pair | Where | +| --- | --- | +| a line and its instructions | the source over the disassembly; the thread between | +| an instruction and what it changes | the change in its own row's annotation; the register across the gutter | +| a pointer and its target | the target's pin; in one panel the `arc`; a `loupe` hung under the pointer | +| a call and its callee | the callee's window under the call row ([`descent`](#descent)) | +| a system call's arguments and the kernel's side | the arguments under the `syscall` row, the kernel's window under them | +| the drawing and its bytes | side by side in the band, the projection across the gutter at one height | +| a call tree and its frames | the tree and the backtrace beside it, both down to the newest; a frame's span on the stack | +| the flags a compare sets and the jump that reads them | their two rows, framed together while the jump is current | + +**The audit.** Against these rules, what moved: + +| Where | Was | Now | Why | +| --- | --- | --- | --- | +| the `syscalls` lens | the kernel's side, on vellum, in the band over the program | the kernel under the `syscall` row, the descent's floor; the band holds the calls so far as strace writes them | the kernel is under the program, and a call's arguments and the kernel's side are now neighbours (mock 14) | +| the backtrace: a panel, the calls lens's view, the backtrace lens, the map | newest on top | newest at the bottom, `#0` last | a call goes down: it reads as the tree beside it does, and the backtrace lens's `#0` sits over the source line it is at (12, 13, 19) | +| a call followed into a function | the window went to the callee; the call row left the screen | the `descent`, when the scene follows the call | the call and its callee are neighbours, and the return has a row to come back to (16) | +| `qword ptr` and its kin | in every operand | gone; a `width` where no register says the size | the operand is shorter and the width is shown only where it is news (17) | + +What stays, and why: + +- **The band's view over the registers.** It is memory over the CPU, + against down is deeper; but under the registers it would be 300 units + from the drawing made of it, and the projection between them would cross + the frame. The band is the idea twice, as drawn and as bytes, and the + drawing and its bytes being side by side matters more. +- **The registers beside the disassembly**, not under it: an instruction + and its register are across the gutter at about one height. +- **The map** keeps the frame's order across its four columns: the drawing + and the source, the disassembly (a descent whole, the kernel at its + foot), memory over the registers, the stack. The backtrace stays at the + foot of the first column, beside the disassembly it is the chain of. +- **The lenses**: a list left to right in list order, an array by index, + a tree down, the far view's time left to right, a loupe hung under its + pointer. None goes against the rules. + ### The map and the minimap **The map** is the working frame unfolded: every panel at its full length, @@ -1110,6 +1332,9 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves: | `dive` | from the map to the working frame | one continuous move in which the windows become the panels and the map becomes the minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; the map, veiled, goes the same 72 f to the minimap's place, its scale from a half to a twentieth, so the windows rise out of it as it falls away; their outlines stay on it and land as the minimap's windows. 72 to 96: the drawing, whose sizes differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: the frame's tags, rules and lanes fade in; the veil on the map lifts as it lands. 96 to 132: still | | `surface` | from the working frame to the map | the dive backwards, a little quicker: 0 to 12 the tags, rules and lanes fade out; 12 to 84, `glide`, the panels shrink into their windows as the minimap grows to fill the frame; 84 to 96 its veil lifts; then the map is still 36 f before anything plays on it | | `flash` | the minimap, at a mark no window shows | a ring 8 across in the mark's colour draws out to 14 and is gone, 12 f, with the mark's own strike or read | +| `descend` | a call the narration follows down | 0 to 12 fire on the call row; rsp struck (24); the stack slides and the return address is struck (30 to 60), as for any call; then 66 to 84 the caller's window closes round its call row (the rows it gives up fade, 12 f; its three glide to its top, 18 f, `glide`); 72 to 84 the call row's plaque becomes the ring; 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 as the lane reaches it; 102 to 126 its rows, top down, 2 f apart, 12 f each; 126 to 138 the advance: the plaque lands on the callee's first row, and the source line goes `waiting` (6 f) where the callee has none. Through a stub's `jmp`: the stub's window shrinks to that row, `pass` (18 f, `glide`), the lane runs on to the next head (18 f), the next window comes in the same way | +| `cross` | a `syscall` row, in a descent | 0 to 12 fire; 18 to 36 the registers that carry the call framed as read, 6 f apart, the argument rows under the row with them (`echo`); 48 to 72 the crossing lane draws down, 3 units, vellum; 66 to 78 the kernel's window opens as it lands, the vellum filling down from the lane's head; 78 to 90 its head and the call fade in, 6 f apart; the work (bytes given or filled, motion.md's chart); `returns` struck; then the answer climbs the lane (24 f) and rax is struck as it lands, the clobbered registers 6 f apart after it, the log's new row fading in (secondary); hold 36; the advance: the kernel's window draws back up into the lane (12 f) and the lane into the plaque (12 f) as the plaque moves on | +| `ascend` | a `ret` out of a descent's window | 0 to 12 fire; 18 to 24 the return address framed as read on the stack; rsp struck (36); 48 to 72 the window closes, its rows fading bottom up, 2 f apart, 12 f each, its head last; 72 to 84 the lane draws back up into the ring; 84 to 102 the caller's window grows back (`glide`), the rows it gave up fading in; 102 to 114 the ring becomes a trail bar, the call row's annotation takes the result (6 f), and the plaque lands on the row after the call; the source line from `waiting` to `current` | | `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 | @@ -1124,7 +1349,8 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves: A step is as long as its content: 0.8 s when only the line moves, 1.5 s for one register, 2.0 s for a register and memory, 3.0 s for a call and 3.1 s -for a return across three levels, 2.7 s for a swap. +for a return across three levels, 2.7 s for a swap; 2.7 s to follow a +call down, 3.6 s for a crossing (4.9 s when it moves bytes), 2.3 s back up. ## Composition @@ -1133,8 +1359,8 @@ for a return across three levels, 2.7 s for a swap. - The working frame holds the band and two columns; the band is two panels, one over each column. The map holds the same panels, whole, in four columns. A column holds panels. A panel holds a tag and rows, - or (a lens) a tag and a drawing. A row holds atoms. Nothing nests - deeper. + or (a lens) a tag and a drawing, or (a descent) a tag and windows of + rows under their heads. A row holds atoms. Nothing nests deeper. - Every panel shows the same moment. A register from one stop beside a stack from another is a lie, however small. - A mark sits on an atom or a row, never on a panel. A panel's only @@ -1188,20 +1414,24 @@ for a return across three levels, 2.7 s for a swap. ## The mocks -`mock/context.py` draws 12 to 14, one function a block under the block's -name; `mock/map.py` draws the working frame from a fresh recording of -`targets/list` (9 to 11, 21), the map (19) and the dive (20); +`mock/context.py` draws 12 to 14, 16 and 17, one function a block under +the block's name; `mock/map.py` draws the working frame from a fresh +recording of `targets/list` (9 to 11, 21), the map (19) and the dive (20); `mock/dense.py` holds that recording's data and draws the marks sheet -(15); `mock/gen.py` draws 1 to 8. Each working frame has a `-480.png` -beside it; the map has its 1080p (`19-map-1080.png`). +(15); `mock/heap.py` draws the heap scene's storyboard (18) from a +recording of `mock/heap.c`; `mock/gen.py` draws 1 to 8. Each working frame +has a `-480.png` beside it; the map has its 1080p (`19-map-1080.png`). ```sh cd design/mock python3 -B context.py && for n in 12-calls-subject 13-sqlite-row 14-sqlite-page; do - resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done + resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done; resvg 16-descent.svg 16-descent.png +resvg 17-operands.svg 17-operands.png +python3 -B heap.py && resvg 18-heap.svg 18-heap.png && resvg -w 480 18-heap.svg 18-heap-480.png 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 +resvg -w 1920 19-map.svg 19-map-1080.png python3 -B gen.py # 1 to 8, then resvg the same way ``` @@ -1210,17 +1440,20 @@ python3 -B gen.py # 1 to 8, then resvg the same way | [9](mock/09-context.png) | `beside`, at rest: `targets/list` stopped at the load in `reverse` (`mock/list-dbg.txt`, moment 2) | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot` with offsets and roles, `pin` row; `call` spans; `insn` current, ahead, outside under a rule and its name; `line`; `bytes` by fields with number, pointer, loose; an `arc` standing in the view; `nodes` with pins under, two names on one; `thread`; marks current, held; the minimap, its windows | | [10](mock/10-context-step.png) | the same, mid-step: the load done (moment 3) | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection`; the read pointer's `arc` at full ink; the minimap | | [11](mock/11-context-lens.png) | `subject`, mid-step | the band at 296 and 200, the drawing a size up, a dump of seven, nine instructions, six slots; the minimap with the subject's windows | -| [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments; `call` spans with arguments; the stack's row with offsets and a role; a `projection` from the return address to the new node; operands of 27 characters whole | -| [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in | -| [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the kernel's side in the band; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed | +| [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments, newest at the bottom beside the tree; `call` spans with arguments; the stack's row with offsets and a role; a `projection` from the return address to the new node; operands of 27 characters whole | +| [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing, `#0` at the bottom over its source line; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in | +| [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the calls so far in the band, strace's way, the newest whole and held; the call through a pointer by its target's name, `→ __pwrite64`; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed | | [15](mock/15-marks.png) | the marks sheet: `current`, `struck`, `held` as A (the first videos), B (the catalogue's) and C (a whiter reading), on rows of the list at the load and the store after it | the source's current line; the pc's row; rip; a struck and two held registers; a dump row struck on the one byte that changed and one held; a lens's cell held and struck; the same rows at 1.35 times | | [19](mock/19-map.png) | the map, mid-step with a loupe open: the same moment unfolded on 3840 by 2160 ([at 1080p](mock/19-map-1080.png)) | the file whole; 69 instructions; memory, the registers, the backtrace whole; the stack from 16 words above rsp, continued at the third column's foot and folded into `more` at the process's start; the loupe as a panel beside memory; `arc`s in memory, the loupe and the stack (the frame chain left to the spans); the key; the thread across the gutter; the working frame's windows outlined | | [20](mock/20-dive.png) | `dive`, four instants on one sheet, each at the working frame's size | frame 0 the map; 24 the windows bright, the rest veiled; 60 halfway, the panels rising out of the map as it falls to the corner; 96 the working frame with its minimap | | [21](mock/21-loupe.png) | the working frame mid-step with a `loupe` open | the loupe hanging from rdi over the registers under it, its node framed, the chain 1004090 → 1004070 → 1004050 as `arc`s in one lane (the view withholds them while the loupe is open); the minimap with the loupe at its place on the map, outlined bright | +| [16](mock/16-descent.png) | the syscalls scene's `open` followed down, four instants of the program column (`ztrace dbg` on `anim/tools/hello.c`, moments 1 to 6) | `descent`: main's window, the PLT stub's under it, libc's `open`, the kernel's window on vellum; `insn` `waiting` and `pass`; the call lane and the crossing lane; `line` `waiting` and the waiting thread; a PLT target named, an indirect jump's target, a `lea`'s result, a named place (the canary), a system call's number and its arguments hanging under it; libc's twelve-digit addresses moving their own window's columns; the descent closed again, the call `ran` with its result | +| [17](mock/17-operands.png) | operands before and after, on real rows of list, hello and libc's `open`; then the row's detail | size words gone; `width` on an immediate store, a byte compare, a sign-extending load; padding faint; a compare's two values and the flags it leaves; conditionals reading them; `lea`'s sum; an indirect jump through `open@got` | +| [18](mock/18-heap.png) | the heap scene, five instants: `ztrace dbg` on `mock/heap.c`, glibc 2.44, after each malloc and free | `nodes` in two rows, a `bin` heading the second (`dummy tcache` before the first free); a free chunk drawn `freed`, its link in its first word; `bytes` read as `size` (`0x20 a m P`) and `protected` (`→ 405050 ^ 405`), notes (`key`, `the old link`); the free list and the program's list as `arc`s; struck bytes, one byte of a pointer struck alone; a `loupe` on the tcache hung from the dump's row of its chunk | | [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` | -| [4](mock/04-malloc-glibc-musl.png) | first pass | `heap`; `freed` | +| [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` (the kernel's side is now the descent's floor, 16) | +| [4](mock/04-malloc-glibc-musl.png) | first pass | the allocator drawn to scale; `freed` (now a scene, not a lens: 18) | | [5](mock/05-memory-write.png) | first pass | a byte grid: the old form of `hexdump`; `struck` and `held` in cells | | [6](mock/06-title-legend.png) | | `card`, the legend | | [7](mock/07-sort-swap.png) | first pass | `array`; `travel` | @@ -1233,8 +1466,13 @@ the band. **Specified, not drawn.** - The `none` split, and the `backtrace` as a panel of its own. -- `insn` annotations for a return, a system call, `not taken`, a jump out - of the window; operands giving way (none in 9 to 14 needs to). +- `insn` annotations for a return, a jump out of the window, a `rep`, a + `lea` with registers in its sum; the flags' echo; operands giving way + (none in 9 to 17 needs to). +- The descent's motion, its fold of a deep chain, a lazy PLT's resolver + row, the vDSO, a descent into a function of the program's own, and the + descent on the map. The registers and stack beside 16's instants (the + strip is the program column only). - `value` classes other than digit, small number and string. - `armed`, `fault`, `attention` and the veil in the context. - A `projection` from the dump for a write. A `link` to a `slot`, and its @@ -1243,10 +1481,13 @@ the band. - `unread` field bytes at a stop that saw only part of a buffer (the page at stop 167, before the kernel took it). - A calls tree small or folded. -- `array`, `heap`, `pages` in the band. -- A loupe opened from the stack, the disassembly or a dump; a loupe typed - by `fields`; two in the working frame; a third closing the first. -- The minimaps of 12 to 14: their recordings hold a stack of 64 words or +- `array`, `pages` in the band. +- The heap scene's working frame whole, its map and minimap (its places + are in [the scene](motion.md#a-scene-libcs-heap-from-the-inside)), a + node travelling between the rows, a bin of the unsorted or large kind. +- A loupe opened from the stack or the disassembly (18 opens one from a + dump's row); two in the working frame; a third closing the first. +- The minimaps of 12 to 18: their recordings hold a stack of 64 words or less and no bytes round targets, so their maps would be mostly gaps. - `surface`, `flash`, a window's outline gliding on the minimap. - A local's name as a slot's role (the recording has none at these pcs). @@ -1260,7 +1501,13 @@ instructions and their lines (12: `ztrace show` on `addr2line`; 13 and 14: `ztrace show` on the sqlite scene's recording, its source from SQLite's amalgamation, and the bytes of the struct and the page as the scene's export shows them, the page's from the recording's -capture of `pwrite64`). The frames' extents are read off the frame-pointer chain. +capture of `pwrite64`; 16: `ztrace dbg` on `anim/tools/hello.c`, built +`-O0 -no-pie -Wl,-z,now` and run under `env -i setarch -R`, its libc rows +from that run's disassembly; 17: the same runs and `objdump -d` of +`/usr/lib/libc.so.6`; 18: `ztrace dbg` on `mock/heap.c`, `x 0x405000 1024` +after each malloc and free). The frames' extents are read off the frame-pointer chain. +The older calls in 14's log show `(…)` for their arguments: this mock's +data has only their names and results. The dump's node bytes are what the chains and the program say the heap holds; its allocator rows are glibc's layout, with the word nothing reads drawn as never read. A recording made under ptrace has seen neither. The @@ -1275,82 +1522,95 @@ still read. ## What this asks of the renderer What the documents say and `anim/src` does not do, as read on 10 November -(`theme.zig` as of 22:37: the marks and the stack's row are in; the 4K -stage of the last round was never built, and is withdrawn); the tokens are -under [Token changes](#token-changes). +at 23:07. Since the last round `theme.zig` has the map and the minimap +(`map.zig`), the loupe (`loupe.zig`), the `arc` and the dump's and the +slot's new columns; whether `dive`, `surface` and `flash` are whole there +is not checked here. The tokens are under [Token changes](#token-changes). -1. **The map**: a second layout at 3840 by 2160 units, the same panels and - rows, each panel at its full length ([the map](#the-map-and-the-minimap)): - the source whole or 69 lines, the disassembly 69 rows, the registers, - the backtrace whole, memory per region touched (32 rows, fieldless rows - folded), the stack from rsp − 128 to its top, the drawing at its subject - size, loupes at nine rows; packed into four columns by content, a panel - continuing in the next column's free space under `continued`, the key - in a column's left foot. It draws the thread and the marks, no link and - no projection, and outlines the working frame's windows. -2. **The minimap**: the map drawn at a twentieth in the caption band's - right end (1664, 912, 192 by 108): text runs as strokes, blocks for tags, - paper and loupes, the marks over them, the windows outlined; the clock's - count moves left of it. `flash` for a mark no window shows. A window's - outline glides with its scroll. The camera never takes it. -3. **`dive` and `surface`**: a transition that draws each working panel - in its own transform (scale and offset), from its window on the map to - its place, while the map, veiled, is drawn in one transform from - filling the frame to the minimap's rect; scales on their logarithms, - `glide`; the panels 6 f apart in the frame's reading order (drawing, - view, source, registers, disassembly, stack), each later one over the - earlier, so that none crosses another mid-flight unseen. The camera - moves one transform for the whole stage and `relayout` lerps boxes at - one text size: neither does this. A sprint, a long run and a far - `continue` are played on the map between a `surface` and a `dive`. -4. **`arc`** ([`arc`](#arc)): in a dump, a loupe and the stack, the lanes - at their left edge, the columns moved for them; standing and full ink; - the frame chain only when touched; a loupe's rows withheld from a dump - showing them. -5. **The loupe** at the working frame's measures ([`loupe`](#loupe)): - five rows, hanging from its pointer, the lift and the shadow; nine rows - as a panel on the map; on the minimap a lift block, its target - outlined. -6. **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). +1. **Direction** ([direction and nearness](#direction-and-nearness)): + the backtrace with the newest at the bottom (`calls.zig` and + `context.zig` still write `newest on top`), the oldest dropped from the + top, `· 2 more above`; the `syscalls` lens's drawing as the log of + calls ([`syscalls`](#syscalls)), the kernel's side leaving the band + for the descent's floor. +2. **The descent** ([`descent`](#descent)): the disassembly as windows a + call deep, each with its head row and its own address width; `insn` + `waiting` and `pass`; the call lane and the crossing lane; the kernel's + window on vellum; folding past three windows; on the map the column + whole. Its verbs `descend`, `cross`, `ascend`. With it, `line` + `waiting` and the waiting thread (primary, 2), and the source's tag + saying where the pc is. +3. **Operands** ([`insn`](#insn), [`width`](#width)): every size word + dropped; a `width` of byte cells where no register of the instruction + has the access's size and the mnemonic does not fix it; `nop` and + `endbr64` faint. +4. **The row's detail** ([`insn`](#insn)'s annotations): a compare's two + values and the flags it leaves, as chips; a conditional's `· reads`, + and its echo on the setting row and rip's flags while it is current; + `lea`'s `=`; an indirect call's or jump's target and the slot it was + read from, the target's name the last thing to go; a PLT stub named in + the operand (`401070 open@plt`) and the function it reaches in the + annotation; places the C library's layout names (`fs:[0x28]`, the + canary); a `rep`'s count; a system call's name and number, its + arguments hanging under it; a ran call in C's form with its result. +5. **Malloc's words** ([`bytes`](#bytes)): field reads `size` (the size, + `A M P` as chips) and `protected` (the pointer protected, the mask, + the arc to the pointer), and a field's note. +6. **`nodes` in two rows** ([`nodes`](#nodes)): the program's list over a + free list, a node travelling between them, the free form (dashed, + hatched `key`, its link from the first word), and the `bin` box + heading the second row. +7. **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`. -**What the recordings must hold for the map**, with the tracer's options: +**What the recordings must hold**, with the tracer's options: -- `--stack 1024`: the stack from rsp to 1024 above it, at every stop, and - the 128 bytes under rsp the tracer now keeps; the map's stack column is - 69 slots and its continuation (about 90), the rest folded. -- `--disasm 69`: 34 instructions above the pc and 34 below, with their - lines; a function the window holds whole needs no more. -- `--around 256`: 256 bytes either side of every telescope target and - every touched address, clipped to its mapping: the map's memory column - is 32 rows round what a step touched, and a loupe's nine rows (80 either - side) fit inside it. -- Unchanged: the source file, the frame chain, the allocations; for the - stack's roles, the call frame information, the locals' places at each - frame's pc, and the first stack pointer, as the last round asked. +- For the map, as before: `--stack 1024`, `--disasm 69`, `--around 256`; + the source file, the frame chain, the allocations, the call frame + information, the locals' places, the first stack pointer. +- **For a descent**, at every stop: the backtrace by the unwind tables (in + since this round, by the tracer's note; the build this round's mocks + were made with still lost `main` at the first instruction of `open`, + `#1 libc.so.6+27781`); for each frame the module, whether it has + source, its function's bounds, and three instructions round its call + row (the return address and the instruction before it); names at every + pc, the first instruction of a function too (`open`'s entry printed + bare, `7ffff7d10ec0`, where its middle printed `libc.so.6!open+261`); + a PLT stub by its symbol (`open@plt`, not `hello+1070`) and its GOT slot + (`open@got`) with the slot's value at the stop; whether the slot is + still lazy. +- **For a crossing**, at the `syscall` row: the number and its name, the + arguments by the call's signature (a descriptor with what it is open + on, a path or a buffer with its bytes, flags by name), the result, the + registers it clobbered. +- `ztrace record --by insn --from main` began in the loader with the + ReleaseFast build used here (`hello`, 120 moments, all in `ld.so`): + `--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). ## Token changes -Against `anim/src/theme.zig` as it is now (22:37): "In theme.zig" is what -is in the file, "Is" what the documents say. +Against `anim/src/theme.zig` as it is now (23:07): "In theme.zig" is what +is in the file, "Is" what the documents say. The map's, the minimap's, the +loupe's and the arc's tokens, the lift's colours, the clock's count at +1648, and `metric.bytes` and `metric.slot`'s new columns are in, as asked. | Token | In theme.zig | Is | | --- | --- | --- | -| `map` | none | `canvas` 3840 by 2160; sides 112, top 96; the stage 3616 by 1688; four columns of 880 at 112, 1024, 1936, 2848; the thread at 1008; the window outline 2 in `dim`, 4 out; panel lengths as listed | -| `minimap` | none | at (1664, 912), 192 by 108, a twentieth of the map; strokes 1 high at 45% toward the page; marks at least 1.5; windows 1 in primary, 1.5 bright for the one in focus; frame 1 in `rule` | -| `canvas.clock_count` | at the stage's right end | ranged right at 1648, left of the minimap | -| `color.lift`, `lift_tag`, `shade` | none | `121c52`, `22317a`, `02061a` | -| `metric.loupe` | none | 880 wide; 5 rows in the working frame, 9 on the map; hangs from the foot of its pointer's row, its left edge 92 left of the pointer's digits; shadow 12 and 16, a deeper one 20 and 26 and 120 to the right; stem 3 | -| `time.loupe` | none | `read` 0.10; `stem` 0.30; `rise` 0.20, shadow 0.30; `frame` after 0.10; `close` 0.20 | | `time.dive` | none | `bright` 0.10, `veil` 0.30, `move` 1.20 (`glide`, 0.10 between panels), `fade` 0.20 at its end, `still` 0.60; `surface` the same, the move first | | `time.flash` | none | 0.20: a ring from 8 to 14 | | `time.caption_max`, `first_step` | none | 12.00; 4.00, 5.00 when a scene opens on the map | | `metric.span.name_max` | none | 300 | -| `metric.arc` | none | lanes 4, 10, 16 (a dump, a loupe), 4 and 10 (the stack); out at 21, head 7 by 8 at 22; rows left at 9 and entered at 15 going up; stroke 2, radius 4; standing at 60% toward the page | -| `metric.bytes.bracket`, `address`; `metric.slot.lane` | 7, 18; 10 | 24, 34 (the bytes 12 after the address, 132 at least); 16 | -| `time.arc` | none | `draw` 0.20 from s+6; `fade` 0.20; `quiet` 0.40 with the cool; `lane` 0.20 | | `metric.calls` small, folds | full only | disc 36, level 38, badge 24 at 6 and 32, mono 20; fold past 13 leaves or 6 levels | +| `metric.width` | none | cells 5 by 10, 7 apart, `dim`, standing on the baseline 3 after the `]`; what follows 4 after the last cell; eight cells and a count past 8 bytes | +| `metric.insn.wide` | none | 12 a digit past seven, per window: libc's mnemonic at 240, its annotation at 624 | +| `metric.descent` | none | callers' windows 3 rows; a head a row (rule 2, name at 40 in Go Medium 18, what it is ranged right in Go 18); the call lane at x 14, 2 in primary, head 7 by 8 into the name; into the kernel 3 in vellum, its head in ink; three windows of code, then a fold row; the kernel's window a head and two rows | +| `metric.node.two_rows`, `metric.bin` | none | rows 110 apart, nodes 136 wide; the bin box 160 by 44 at the row's left, its count on a 30 square on the shoulder; a free node's outline dashed 12 on 8 | +| `time.descend` | none | `close` 0.20 then 0.30 (`glide`), `ring` 0.20, `lane` 0.30, `head` 0.20, `rows` 0.20 a row 0.03 apart, from 1.10 after the fire; the step 2.70 | +| `time.cross` | none | the registers framed 0.10 apart from 0.30; `lane` 0.40 from 0.80; the kernel's window 0.20; the answer up 0.40; the step 3.60, 4.90 when it moves bytes | +| `time.ascend` | none | `close` 0.20 a row, 0.03 apart, from 0.80; the lane back 0.20; the caller's window 0.30 (`glide`); the step 2.30 | Unchanged and already there: the 1920 stage and its splits, the palette with the marks of the last round (`wash`, `struck` `b54f42`, the corner), @@ -1373,6 +1633,9 @@ camera's scales. 7. `call` spans; the three splits and `relayout`; the camera at x1.5. 8. The other lenses in the band. 9. The map and the minimap; `dive` and `surface`; the loupe. +10. Operands without size words and `width`; the row's detail; the + `descent` and `descend`, `cross`, `ascend`; malloc's words; `nodes` in + two rows. Export: |
