diff options
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: |
