# canim: the design language This is the catalogue. Everything that can appear in a canim frame is a **block** with a name, specified here once; everything larger is a composition of blocks. The names are the ones the code uses. A gallery scene that draws every block in every state is the test of this page. - How blocks move is the [verbs](#6-verbs) below; the reasoning and the full timing charts behind them are in [`motion.md`](motion.md). - The blocks drawn: [`mock/`](mock). [Which mock shows which block](#the-mocks). - The numbers are tokens in `anim/src/theme.zig`: [what to change there](#token-changes). ![the working frame, mid-step, its minimap in the corner](mock/10-context-step.png) ## The rules 1. **Lapis page, vellum ink.** A deep blue page, cream text, gold for where execution is, vermilion for what just changed. 2. **Ink says what a thing is; paper says what happened to it.** The colour of a value's digits is where it points, or that it is a keyword or a string. A fill, a frame, a turned corner is an event. The two never share a channel. 3. **Every mark has its own form.** Written is filled, read is framed, changed is ticked, freed is hollow, unknown is two dots. Nothing is told by hue alone. 4. **Solid vellum is the kernel**, and nothing else. 5. **Panels are acme windows.** A tag, a 2-unit rule, a body. Square corners, no shadows, no gradients, no glow. 6. **The whole context, always.** Every register followed as far as it points, the instructions round the pc, the source, the stack: in the same place in every frame, as pwndbg shows them. A lens (a list, a tree, an array) is drawn over that state and never instead of it. 7. **Panes are views of one machine, and the ties are drawn.** A source line and its instructions, a register and what it points at, a run of bytes and the node drawn from them: each relation has a form, a route 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 Six layers. A block is made only of blocks from the layers above it in this table. | Layer | Block | Is | Options and states | | --- | --- | --- | --- | | 1 atom | [`address`](#address) | hex digits in the ink of where they point | `lead`, `name`, `rwx` | | | [`value`](#value) | anything that is not an address | by class: digit, number, negative, string, fd, flags, bool, char, unknown | | | [`arrow`](#arrow) | the sign between two things in a chain | `points`, `holds`, `more` | | | [`hop`](#arrow) | a `points` arrow and the address it leads to | | | | [`byte`](#byte) | two hex digits of a dump | `number`, `pointer`, `text`, `loose`, `unread`; `pad` | | | [`mark`](#mark) | what happened to a thing | `current`, `armed`, `struck`, `held`, `read`, `trail`, `allocated`, `freed`, `fault`, `attention`, `unknown`, `kernel` | | | [`plaque`](#plaque) | a solid label under the current mark | `gold`, `chip` | | | [`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`, `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, 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; a [`descent`](#descent): a window a call deep, the kernel at the floor; a [`graph`](#graph): the function's blocks | | | [`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) [`syscalls`](#syscalls) [`blocks`](#graph) `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 | | | [`echo`](#4-ties) | the same mark in two panels at once | for a step | | 5 frame | [`stage`](#5-the-frame) | the working frame: the band and the two columns | split `none`, `beside`, `subject` | | | [`segments`](#segments) | the process's address space to scale, each end enlarged, its bands' addresses at their edges | treatments A (default), B, C; the ink's source: a band framed when a word is inked; a dump's place | | | [`aligned`](#aligned) | the source and its instructions in one panel, each line level with its code | `interleaved`, `columns`; a split a scene chooses | | | [`pair`](#pair) | two runs of one program against each other, a seam between them | `only here`, `differs`; the shadow on an ASan run's stack | | | [`map`](#the-map-and-the-minimap) | the working frame unfolded, every panel whole: 3840 by 2160 | the key | | | [`minimap`](#the-map-and-the-minimap) | the map at a twentieth, in the working frame's corner | windows, marks, `flash` | | | [`clock`](#clock-and-caption) | where in the recording | | | | [`caption`](#clock-and-caption) | the narrator | | | | [`veil`](#clock-and-caption) | page over what a beat does not touch, or a pace cannot show | | | | [`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 | | | | [`regroup` `ink` `enlarge` `column` `frame up` `decode` `align`](#6-verbs) | what building a view does (the introduction) | | | | [`leave` `turn` `spread` `gather`](#6-verbs) | what a graph does: a block left by an edge, a loop's turn, rows into blocks and back | | | | [`dive` `surface` `flash`](#6-verbs) | between the map and the working frame | | | | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | ## 0. Tokens ### Grid **The working frame** is 1920 by 1080 units, at 60 frames a second; a 4K master is two pixels a unit. It is where a scene is told, and everything in it reads at 1080p. **The map** is 3840 by 2160 units at the same type size: the working frame unfolded, every panel at its full length. It is shown filling the frame (at half its size, so at 1080p its text is texture), and small in the corner of the working frame as the [`minimap`](#the-map-and-the-minimap). The working frame's panels are windows onto the map's columns. | Token | Value | | --- | --- | | context mono | 20: an advance of 12, rows of 24, in the working frame and on the map alike | | panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides | | between panels | 12 | | columns | working frame: two of 880, at x 64 and 976; the gutter between them, 944 to 976, belongs to the ties. Map: four of 880, at x 112, 1024, 1936 and 2848, 32 apart | | strokes | 2: rules, frames, chain arrows, a projection. 3: a link, the thread, a lens's frames, a loupe's stem | ### Colour | | Hex | On page | Use | | --- | --- | --- | --- | | page | `0a1030` | | the ground; panel bodies | | raised | `16245f` | 1.3 | tags, node bodies, the paper under a field's bytes, chips | | well | `101a48` | | a node's pointer half | | rule | `3a4a8a` | 2.2 | rules, quiet brackets | | bright | `fff8e8` | 17.6 | titles, a set flag, the newest frame's name | | primary | `eee6d2` | 14.9 | numbers, names of code, plain code | | dim | `9aa6d9` | 7.8 | register names, `loose` bytes, notes | | faint | `6a7ab8` | 4.5 | chain arrows, line numbers, a decimal beside its hex | | ink | `050a24` | | letters on a solid mark | | wash | `212644` | 1.2 | the current row's band: bright a tenth of the way over the page, opaque | | lift | `121c52` | 1.2 | a loupe's surface; its tag `22317a` | | shade | `02061a` | | a loupe's shadow, the one shadow there is | **Regions: the ink of an address**, as pwndbg colours them. The legend is the registers' tag, always on screen. | Points into | Ink | On page | Also told by | | --- | --- | --- | --- | | stack | `f2d675` | 13.0 | by far the lightest | | heap | `86b6ff` | 9.0 | | | code | `ff8f9a` | 8.5 | its name always follows | | data, writable | `d59cf5` | 8.8 | | | writable and executable | its region's | | a 2-unit underline | | read-only data | primary | 14.9 | | | a string | `b5e8c8` | 13.6 | its quotes | Known weakness: heap, data and code have one luminance, so between those three the ink is hue alone, as it is in pwndbg. A code address has its name; heap and data have only their digits. **Marks: the colour of an event.** Solid, and the ember it cools to. | Role | Solid | Ember | | --- | --- | --- | | current | gold `e8c46a`, on the plaque only; the row's band is `wash` | trail `ae9350`, `746235`, `463b20` | | write | vermilion `ff6a4a`, for the arm, the turned corner, a projection; a strike's paper `b54f42` (vermilion 70% over the page), its digits bright | `5a2218` | | read | `6fd6e6` | `1c4652` | | allocated | `7fdc9a` | `1f4a33` | | kernel | vellum `eee6d2` | | **Code**: plain primary; keyword and mnemonic `c0dcff` bold; string and number `b5e8c8`; comment dim italic. **Pigments** name an object across views, at most four: ochre `8a5e0c`, teal `17707c`, madder `a03060`, malachite `1c7450`, violet `6a3fb0`, azurite `2f5fc4`. Never a ground under region ink. ### Type | Face | For | | --- | --- | | JetBrains Mono NL Medium | all mono under 30 | | JetBrains Mono NL Regular | mono at 30 and over | | JetBrains Mono NL Bold | keywords, mnemonics, a struck value, plaques, pins | | JetBrains Mono NL Italic | comments | | Go, Go Medium, Go Bold | captions and notes; tags; titles | NL because the plain family's ligatures turn `->` into a sign that is not in the source. Medium because thin strokes on a dark ground die first in a stream. OFL and BSD; `/usr/share/fonts/TTF/`, `/usr/share/fonts/go/`. | Mono | Advance | For | | --- | --- | --- | | **20** | 12 | the context, the dumps, a loupe, the map | | 25 | 15 | a lens's values beside; its labels and pins as subject | | 30 | 18 | the context under the camera at x1.5 | | 35 | 21 | code inside a caption | | 45 | 27 | a subject lens's values; a value in flight | | 60 | 36 | a title card | Sans: 18 notes and legends, 20 tags, 40 on 54 the caption, 44 and 116 a card. **Floor: mono 20, sans 18.** At 480p no digit at 20 can be trusted, so: **nothing the narration depends on is only at 20.** It is also in the caption at 35, or the camera goes to it. On the map, filling a 1080p frame, mono 20 is 10 pixels: texture, which the caption carries; in a 4K export it is 20 pixels and reads. ## 1. Atoms ### address Lower-case hex, **unbroken**, as long as it is, no `0x`, no leading zeros: `28b41090`, `7ffe970f17b0`, `1001926`. Its ink is its region. | Option | Draws | | --- | --- | | `lead` n | the first n digits at 60% of the ink toward the page. Used in a column of addresses (disassembly, stack slots, a dump's gutter) with n = the digits every row shares, leaving at least two: the eye reads the part that changes | | `name` | code only: `name+offset` in primary, 10 units on; the module when there is no symbol, its offset from the module's first mapping: `libc+27781` | | `rwx` | a 2-unit underline | States: plain; `struck` (bold, in ink, on solid vermilion 5 wider each side); `read` (a 2-unit frame, 6 out); `held` (a turned corner at its top left). Data: a word and the mapping it lies in. Mocks 9 to 11, everywhere. ### value What is not an address. The tracer classifies; the class decides. | Class | Because | Shown | | --- | --- | --- | | digit | under 10 | `4` | | small number | 10 to 0xffff | hex, and its decimal after it, faint: `0x21 33` | | large number | larger, not in a mapping | `0x` and its hex, unbroken, primary | | small negative | within 4096 of 2^64 | `-1` | | string | a pointer to printable bytes and a NUL | `"..."` in string ink, C's escapes; cut with `…` and no closing quote, never under six characters | | file descriptor | a signature or a type says so | the number, and faint what it is open on: `3 "note"` | | flags | eflags; an argument a signature calls flags | names; bits no name covers as `0x` and their hex: `O_RDONLY 0x8000`. Never bare hex | | boolean, character | the debug info types it so | `true`; `0x41 'A'` | | unknown | never observed | two dots | A typed value follows its type: an `int` is decimal alone, a pointer an address alone. Mocks 9 to 11 show digit, small number, string; the rest are not drawn. ### arrow 30 wide: a 2-unit shaft and a head 8 by 10, faint. | Kind | Reads | pwndbg | | --- | --- | --- | | `points` | which points to | `—▸` | | `holds` | which holds (what follows is not an address) | `◂—` | | `more` | and goes on: `points` and three 3-unit dots | | A **hop** is a `points` arrow and the address after it: the unit a chain is counted, cut and re-followed in. ### byte Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth. | Kind | Ink | Paper | | --- | --- | --- | | `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 | `unread` is about the stop shown, not the recording: memory the recording watches (the stack it records, a heap it tracks) is known from its last observation; memory it does not watch is known only where that stop read it ([`seen`](#hexdump)), and an older stop's bytes there are drawn as unread, since they may be out of date. `pad`: in a number stored low byte first, the bytes above its highest non-zero byte are at 45% toward the page: `70 10 b4 28` stands out of `00 00 00 00`, and is the address `28b41070` read from the right; stored high byte first (`big`), the zero bytes before its first non-zero one: `00 03`. A mark covers the bytes whose value changed, never more: see [`bytes`](#bytes). Mocks 9 to 11, 13 and 14. ### mark What happened, on paper and never in the letters. | State | In the context (mono 20) | In a lens's cell | | --- | --- | --- | | `current` | a gold plaque on the label, and across the row a white wash (`wash`) | the same | | `armed` | a 2-unit vermilion frame, the old value still in it | 3 units | | `struck` | the softened vermilion (`b54f42`) behind the value, 5 out each side; digits bold, bright | the same, the cell's fill | | `held` | a turned corner: a vermilion triangle 9 on its sides at the value's top left, for three steps | the same at the cell's top left, 12 | | `read` | a 2-unit frame in read's colour, no fill | 2 units, 2 out | | `trail` | a 4-unit bar at the row's left edge: three tones, newest first | | | `allocated` | | ember block in a solid frame | | `freed` | | hollow, dashed 12 on 8 off, hatched | | `fault` | hazard bands round an ink plaque naming it | the same | | `attention` | a 2-unit bright frame | 3 units; a veil on the rest | | `unknown` | two dots | two dots | | `kernel` | the ground is solid vellum | the same | One gold mark a panel. One step's writes in vermilion at a time. Gold is kept for the plaque, the pc's marker, rip's name, the thread and the trail: where execution is, as a sign and not as a band. The first videos drew `current` as a gold ember across the row, `struck` as solid vermilion with ink digits, and `held` as a tick left of the value: the band was the strongest thing in a dense frame, the solid strike glared, and the tick read as a text cursor. [Mock 15](mock/15-marks.png) sets those (A) beside these (B) and a whiter reading (C: a white plaque, a white strike framed in vermilion, a bar under the held value) on the same rows. Mocks 9 to 18 show current, struck, held, read, trail, unknown; 1 to 8 the rest. ### plaque A solid label. `gold`: behind the label of a current row, letters bold in ink (rip's name, 54 wide; a line number, 50; the pc's marker, 24, with an ink triangle). `chip`: raised, 32 by 20, behind a set flag, letters bold and bright. Nothing else is a plaque: a register's name at a target is a [`pin`](#pin). ### pin A name at the thing it points to, and a head in the target's region ink that touches the target. A register's name is bold primary; a variable's (a pointer the debug info names: `cur`, `head`) is bold in the ink of where it lives, stack for a local and data for a global, so `cur` under a heap node reads "on the stack, pointing here". It answers "who points here", and it is a [`link`](#4-ties) at rest. | Form | Where | Anatomy | | --- | --- | --- | | `row` | a row's lane (the stack) | the names, then a head 9 by 12 pointing right at the row's address | | `under` | under a drawn node or cell | a stub 3 wide rising to the node's bottom edge, head 10 by 10; names 9 either side of the stub | A pin for every register whose value is exactly the row's or node's address, and for every variable the scene names, from the opening; three names, then a count. No box, no fill. - **Names keep their side.** On an `under` pin the first name to come is left of the stub and the next right of it. When one leaves, the others stay where they are, and the next to come takes the free side. Two names never print in one place. - **Names keep their order.** On a `row` pin the names are in pwndbg's order of the registers (`rbp rsp`), variables after them. A name that comes takes its place in that order and the others slide aside for it (12 f, `standard`) before it lands; one that goes leaves, and the others close up after (12 f). A travelling `rsp` is the same pin on every row it passes. - **A pin is one thing.** One register or variable has one pin, and it travels between the things it points at: it never jumps, and is never in two places ([`travel`](#6-verbs)). Mocks 9 to 12. ### bracket A span marked at its edge: a stroke down the span and a serif at each end, toward the span. `quiet`: 2 units, serifs 5 (a node's row in a dump, at 60% of its region's ink; an older call frame, in rule). `tie`: 3 units, serifs 6 or 7, in the ink of the tie it ends. ### tag 24 high, raised. A 12-unit box 8 in: solid gold where the narration is (`focus`), a faint 2-unit outline elsewhere. The title, Go Medium 20, 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 its far end and says so. ### chain `address (points address)* (holds value)?` - A code address ends a chain with its name. A string ends it in quotes. - **Depth** is the recording's. **Cut** where the row's `room` ends: a string is shortened first, then the chain ends early in `more`. Nothing is taken from the middle. - **Marks** are per hop. If the first is struck the register was written and the rest are followed again ([`extend`](#6-verbs)); if a later one, memory changed under a pointer that did not, and the turned corner sits on that hop alone. - No lines to targets. Thirty chains would be a net; a chain is tied to its target by ink, by digits, and by the target's pin. ### reg A name (dim) 12 in; its chain from 72; room to 12 from the edge. `rip`: gold plaque on the name, the wash across, the address in code's ink and its name. Never struck. Its row carries **flags** at the right end: eight names on a pitch of 42. Set: upper case on a chip. Clear: lower case, dim. Changed: a turned corner. (The value `0x206` is not drawn: the names are the value.) ### slot A word of the stack, pwndbg's way and a little more. | x | Column | | | --- | --- | --- | | 4, 10 | arcs | the [`arc`](#arc) lanes: a word holding the address of another slot in the window | | 16 | pins | the `row` pin's lane, to 112: every register whose value is this word's address | | 172 | offset | from rsp, hex, `+18`, faint, ranged right in four characters (`-8` above rsp) | | 184 | address | stack ink, `lead`; then the chain, its first hop the word's content | | 88 | shadow | in a run built with AddressSanitizer: the shadow byte that stands for this word's eight bytes, a `byte` cell in the pin lane's end, before the address it stands for (a fake frame's words have no offset from rsp, and no pins). `00`, addressable: faint, no paper. `f1` `f2` `f3`, the stack's left, middle and right redzones: bright on the `freed` hatch, the poison's sign. `01` to `07`, the first k bytes addressable: bright, the hatch over the other 8 − k eighths of its cell. The panel's tag gives where the shadow is, `shadow at addr >> 3 + 7fff8000` | | right | role | what the word is, where the recording knows it, ranged right where the chain's room ends: `saved rbp`, `saved rbx` (dim); a local's name (primary), and which part of the word when it is narrower (`n, high half`); at the process's start `argc`, `argv[0]`, `argv end`, `envp end`, `auxv` (dim) | | 14 from the right | span | the [`call`](#call) bracket, its name left of it | A return address needs no word: its chain is code, named (`10018b0 main+80`), and its frame's bracket ends on it. Room runs out from the right: a span's name is never cut, a role is never cut, and the chain on the rows they sit on ends 12 before them, cut by its own rule (`sqlite3BtreeInsert` beside `7fffffffe980 → 7fffffffeb90 → …`). `free`: a word above rsp, which the stack has not reached. Shown only while the window is held still for the camera ([`visit`](#6-verbs)): its address at 60%, its word in faint, no chain, no pin. A push fills it. ### insn An instruction, pwndbg's way: what it is, and what its operands are now. | x | Column | | | --- | --- | --- | | 2 | mark | a gold plaque 24 wide (current) or a trail bar 4 wide (ran) | | 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; `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. 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. | State | Draws | | --- | --- | | `current` | plaque, the wash across; annotation in full ink | | `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: | It | Annotation | | --- | --- | | 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`. The value is read at the access's width: a 4-byte load of `n` is `7fffffffecc4 ◂ 15`, not the word round it | | writes memory | the same chain; the value after `holds` is `struck` | | only sets a register | a small `reg`: `rax 28b41090 ◂ 4` | | 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 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; 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. `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 six. Everything right of the column moves by the extra (12 a digit), the gold plaque widens by as much (50 + 12 a digit), and the text loses as many characters (64 for six digits). The width is the program's, not the window's, so a scroll across 99 999 does not shift the text. The disassembly's `line` column follows the same width (see [`insn`](#insn)). Mocks 13 and 14. ### bytes A hexdump row. Its runs come from the types of what the program's pointers reach: a run is one field of the element's type, an `int` 4 bytes and a pointer 8, never two fields and never a store's width. | x | Column | | | --- | --- | --- | | 4, 10, 16 | arcs | the [`arc`](#arc) lanes: pointers to rows of the same dump | | 24 | bracket | `quiet`, on a row that holds a drawn thing; `tie` when a projection ends here | | 34 | address | region ink, `lead`; at 60% on a row that holds no drawn thing | | 132 | sixteen `byte`s | on a pitch of 30, 12 more after the eighth | | 640 | reading | what the runs read as, left to right, a character apart: a number in decimal (in its byte order); a pointer as `points` and its `address`, `NULL` dim; text in quotes, C's escapes, in a string's ink; a run left to the eye, or `loose`, as nothing; the chunk's size word before an allocation as a note in Go 18, faint (`malloc's: a chunk of 32`). Cut at the panel's edge with a faint `…` | **Wide address.** The bytes begin 12 after the address ends, and at 132 at least: an address of up to seven digits leaves them at 132; the stack's 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, not a table: a page header's five numbers would not fit a pitch of three characters, so no reading is ranged in a column, and two rows' readings need not line up. Marks: `struck` (the paper solid vermilion, digits bold in ink) covers the bytes whose value changed between the two stops, inside one run, from the first that changed to the last: a pointer whose low byte alone moved is struck on that byte, and two `int`s swapped are struck as two runs of 4. A byte stored with its own value is not marked: the recording sees values, not stores. `read` (a 2-unit frame 3 out) frames the run read. `held` is a turned corner at the top left of what was struck. A struct wider than a row spans rows, and its bracket spans them. ### call One frame of the call chain, in two forms. - `span`, on the stack: a bracket 14 in from the panel's right edge down the slots that are the frame, and left of it the function's name, Go Medium 18; for the function a `calls` lens draws, its arguments as a call, `fib(4)`: two frames of one function are told apart, and the digits are the ones on its node. The name is whole up to 300 units (`sqlite3PagerCommitPhaseOne`, 26 characters, is 240), then cut with `…`; the chains beside it make room ([`slot`](#slot)). `newest`: gold bracket, bright name. Older: rule and dim. A frame that runs past the window has no serif at that end. - `row`, in a backtrace panel: `#n` at 12 (a gold plaque 40 wide on the newest), the name and offset in primary at 60, the arguments at 384 (`n=4`, primary), file and line ranged right, dim. Arguments where the debug info gives them. ### arc A pointer whose target is a row of the same panel is drawn, not only read: an arc from the pointer's row to the row it names, in lanes at the panel's left edge. It is the disassembly's jump lane given to data, in every panel of rows that holds pointers: a dump (the band's view, `memory`), a [`loupe`](#loupe), the stack. | Part | Drawn | | --- | --- | | lanes | a dump and a loupe: three, at 4, 10 and 16 from the panel's left edge (the quiet bracket moves to 24, the address to 34, the bytes 12 after it, 132 at least). The stack: two, at 4 and 10 (the pins start at 16) | | arc | 2 units, corners of radius 4, in the ink of the region pointed into: out of the pointer's row at its left (x 21), along its lane, into the target's row at its left, head 7 by 8 at x 22, before the bracket and the address. Going up it leaves its row 9 down and arrives 15 down (going down, 15 and 9), so a chain of pointers (1004090 → 1004070 → 1004050) runs in one lane without touching | | ink | standing: 60% toward the page. Full: in the step that writes or reads the pointer, and always in a loupe, which was opened to show them | | a target mid-row | the head on its row; the `read` or strike on the target's own bytes says which | **Nesting.** Overlapping spans take separate lanes, the longest outermost; spans that do not overlap share one. Nested arcs never cross; interleaved ones cross once, as jump arrows do. Three lanes (two in the stack) is the most a panel holds before it is noise: past them the arcs of the step come first, then the shorter; the rest are only read, and nothing is hidden, since every pointer's reading names its target. **Out of the window.** A pointer whose target row is in the same region but not shown: in the step that writes or reads it, a stub along its lane to the panel's rule, head on the rule; otherwise nothing. No count, unlike a link's stub: the lane has no room for one, the reading names the address, and the minimap shows where. **Which form carries a pointer**, when more than one could: - **In a panel**, between its own rows: the arc. The stack's frame chain (a saved rbp) is the exception: the `call` spans already draw the frames it makes, so its arc is drawn only in a step that writes or reads it. - **A loupe** carries the arcs among its own rows; a dump showing the same rows withholds them while it is open (one place, the one opened for it). A loupe's stem already ties the pointer it opened from; a loupe never opens for a target its own rows hold. - **The lens's drawing** draws the same pointer as its arrow (a node's `next`); the view's arc is that pointer's bytes. Both stand: they are the idea and the machine, tied by ink and digits, and a step that turns the pointer turns the arc at the memory level and the arrow at the idea's. - **A flat chain** (a register's, a stack word's) whose hop lands on a row of another panel: its `pin` where that panel has a pin lane (the stack, a node); otherwise ink and digits. In the step that sets it, a `link`. No standing line across panels: an echo of the target's row whenever the pointer's row is current would flicker on every step. Its motion is under [`arc`'s verbs](#6-verbs). Mocks 9 to 11, 19, 21. ## 3. Panels A panel is a tag and rows. Its rows never reorder and none is hidden to make room. ### registers Seventeen `reg`s in pwndbg's order: rax rbx rcx rdx rsi rdi rbp rsp, r8 to r15, rip (with the flags). Tag: the region legend. 440 high. Reads the moment's registers and mappings. ### stack `slot`s from rsp, low addresses on top: eight; six when the lens is the subject. `call` spans down its right edge for every frame in view: the backtrace, drawn on the words that are each frame. rsp and rbp are pins in its lane. Reads the stack words, each frame's extent (the frame-pointer chain, or the unwinder's CFA), and for the roles the saved registers (the frame-pointer chain; the call frame information for the prologue's pushes), the locals' names and places (the debug info at the pc), and the first stack pointer (argc, argv, envp, auxv). **The window** is on the newest frame: the words from rsp to its return address, `[rsp, rbp+16)`. It is a window onto the map's stack column, which runs from 16 words above rsp to the stack's top. - Where the frame is no longer than the window, the window's top is rsp and the caller's words fill the rest. - Where it is longer, the window scrolls down it by whole slots ([`scroll`](#6-verbs)) to keep the slot a step touches in its middle rows (the third and fourth of six; third to sixth of eight), and stays there until a step touches a slot outside them. Its top never passes above rsp. - A push or a call moves the top with rsp: the rows slide one slot (18 f, as rows making room), at the memory level, before the new word is armed. A window going farther than its height fades through instead ([`scroll`](#6-verbs)). - While the camera is on the stack the window holds still ([`visit`](#6-verbs)): pushes fill `free` slots in the middle of the frame, and rsp's pin climbs to them. Tag: `six words from rsp`, or the range when scrolled (`rsp+20 to rsp+48`), and `· the frames they belong to`. ### backtrace `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, 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 stops share, counted from the oldest, slide to their new depth (24 f, `glide`), their numbers changing at the middle of the slide; then the new frames fade in (12 f), newest last. A frame's `#n` is its depth, not its identity: the slide is what says it is the same frame. ### source A window on the whole file, scrolled by whole lines to keep the current line in its middle third. Fourteen lines; eight beside a lens (the loop in hand); ten when the lens is the subject. Tag: the file, and `lines 19 to 26 of 42`. A line farther than a window away (another function in a file of 262 899 lines) is not scrolled to: the window fades through ([`scroll`](#6-verbs)). Line numbers are as wide as the program's largest ([`line`](#line)). On the map the file is whole, or 69 lines round the current one when it is longer. ### disasm Seventeen `insn`s in address order: the pc's, eight above, eight below. Nine (four, the pc, four) when the lens is the subject. - Rows above the pc are the function's own instructions where it has them; near its start the window stays full from below. - Rows of another function are `outside`: plain, under a rule and its name. - The rows that ran in the last three steps are `ran`, above or below the pc: with the jump lane they show how control came here. - Tag: the function's name. 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`, one row after it (the row it will return to) and at least one before: three rows. The rows the deepest window does not use go to the nearest caller, above its call row; it never keeps more than the one row after the call, so the callee's head sits directly under its return row. Where the caller's function starts first, the rest go to the deepest window, its neighbours `outside` | | 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). ### graph The disassembly's other form: a function as a graph of its basic blocks, with what the run did on it. It is drawn with its rows at the map's size (the larger scale), and as shapes in the working frame's `blocks` lens. Execution flows down; the one thing that climbs is a loop's back edge. | Part | Drawn | | --- | --- | | a block | a box of `insn` rows, a 2-unit `rule` frame; a head of 24, raised: its first address in code ink, its lines (Go 18, faint), ranged right how many times the run has entered it (`×11`, primary). Not yet reached at the moment shown: its head on the page, no count. The pc's: a 2-unit gold frame | | its rows | the offset from the function's start (`+65`, faint, ranged right at 72) in place of the address, which the head carries; the line at 116, on a run's first row; the mnemonic at 128; the operands at 212, as [`insn`](#insn) draws them; a jump's or call's target an `address`. The annotation only in the pc's block (and its rows that ran in the last three steps). As wide as its widest row, 300 at least | | a long block | over 16 rows: its first four and last four, a `more` row between (`→ … 9 rows`), unless the pc is in it | | a call | not an edge: a hook out of the block's right side at the call's row and back in a row down (2, `dim`), the callee's name after it (`swap`) | | the way out | under a block that returns, a stub 14 down and a bar 28 wide | | a forward edge | taken, not taken, a jump, a fall-through: out of the block's bottom on the side its target lies on (40 in from that side, or the middle when it is straight below), along the middle of the gap under its layer, into the target's top; several into one top 48 apart in their sources' order; corners 8. One that would cross a block runs in the graph's right channel, 32 right of its widest layer | | which is which | the jump's row names its target and the target's head shows the same digits; the fall-through is the other. No hue says it | | a back edge | an edge to a block at its own layer or above: a loop. Out of the bottom, down 14, left to its loop's lane (left of every block, 16 apart, the outermost farthest), up it, into the header's head from the left. Its turns so far on the lane under the turn in, Go 18 faint (`×5`); a turn landing strikes it | | an indirect jump | `jmp rax`, a table: a stub 24 down and `more`'s dots, faint `targets not known`; each target the run takes becomes an edge as it is taken | | a tail jump | a jump out of the function: a stub 24 down from the block's bottom and the function it goes to, its name in primary; no bar, since the function does not end here but in the one it jumped to | | a call that does not return | `abort`, `exit`, `__stack_chk_fail`: the call's hook goes out and does not come back, and the block has the way out's bar | | ink | never taken in the recording: `rule`, 2. Taken: `dim`, 2, the run's count by a conditional's ports (`10`, `7`). The last three taken: the trail's golds, the newest 3 units | **Layout.** Back edges are found by a walk from the entry in address order; every other edge goes down a layer or more: each block one layer under the deepest that leads to it, and the blocks that return in the last. In a layer a block sits under the predecessor that reached it most often in the recording, so the hot path is straight down; then under the fall-through's; a taken target to the right of it; then the order that crosses fewest edges. A loop's body hangs between its header and the block that turns back, right of its lane; nested loops nest their lanes. Layers 48 apart, blocks 56 apart, lanes 16 apart from 24 inside the panel. **Too big for its place**, in this order: the blocks the whole recording never reached fold, each connected run of them one dashed box, its offsets and its count (`+5b to +b3 · 4 blocks never reached`) and, where the scene names it, what it is (`multi-threaded: a cancellable call`); long blocks fold; a loop the pc is not in and will not enter again folds to one box (`loop at +5f · 3 blocks · 11 turns`); then the panel pans by `scroll`'s rules, the pc's block in its middle third. **What the recording knows.** By instruction, every jump and return carries the edge it took, so the path, the counts and the trail are exact. By line or by breakpoint only the blocks the stops are in are known: their visits are counted, the edges are drawn by kind in `rule` with no counts, and there is no trail. A function past 2 048 instructions has its blocks without their text (`sqlite3VdbeExec`, 2 510 blocks): it is drawn as the `blocks` lens draws, its blocks as shapes, on the map too. Code with no bounds (start-up, JIT code) has no graph and stays linear. **What a static graph cannot show**, and this one does: how often each block was entered and each branch went each way, the edges never taken, the path the run took (the trail), the block the pc is in, and the blocks the run will reach but has not yet. **Where it lives.** - **The map** draws the disassembly column in this form whenever the recording has the function's blocks (the linear 69 rows otherwise, or when the scene asks), two columns wide (1792); the panels after it repack. The source is beside it; the thread is its digits (the gold line number in the pc's block and the source's plaque): no line crosses the lanes. A descent on the map stacks graphs: a caller folded to the block that holds its waiting call and one block either side, the callee's graph whole under it, the kernel's window under that. - **The minimap** shows it at a twentieth: block outlines, row strokes, edges 1 px, the pc's block gold. A sprint on the map reads there as the gold going from block to block. - **The working frame** keeps the linear rows (rule 6) and shows their blocks: a 2-unit `rule` across over each block's first row, and the block's visits ranged right in that row's annotation room (`×11`, faint) when it is free. The graph with its rows is not drawn there: two blocks' rows barely fit side by side in 880, and the same rows twice are noise. - **The `blocks` lens**, for a scene about control flow: its drawing the graph without text, a block a box 24 high, as wide as its rows (10 a row, 132 at least), its offset and visits, the pc's framed gold 3, the edges, lanes and trail at half measure (layer gap 12, lanes 10 apart); its view, over the state column, is the disassembly itself, seven rows round the pc (five beside), moved out of the program column, which then holds the source alone (twenty lines as subject). No row is drawn twice: the box is the place, the view the text, and the pc's gold is on both. Its motion is [`leave`, `turn`, `spread`, `gather`](#6-verbs). Mocks 22 to 25. ### lenses A lens is the band across the top of the stage: **a drawing, over the program column, and over the state column the pane the drawing is a view of**, each a panel with its own tag. The gutter between them is the ties', as it is below. Beside the context both are 152 high; as the subject the drawing is 296 and its view 200 ([the frame](#5-the-frame)). On the map the drawing keeps its subject size and the view is its region whole. | Lens | Drawing | Its view | Mock | | --- | --- | --- | --- | | `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 | | `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 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 | `memory`, on the map, is the column of the regions the scene's steps 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 is not a `relayout`: the backtrace gives way to the kernel's side when the row reaches `pwrite64`. **What a new lens must provide** to fit the frame: 1. A drawing that fits 856 by 116 (`beside`) and by 260 (`subject`). 2. Its view, a pane of rows that fits the state column (five beside, seven as subject; the region whole on the map), and for every element the bytes, slot or register it is drawn from. 3. A `place` for every element, so ties can land. A 12-unit lane clear at the top of the drawing and one at the bottom: **bytes from its view arrive from above; pointers, and a frame from the stack, from below.** 4. Each mark on its cells: `current`, `armed`, `struck`, `held`, `read`. 5. Its `establish`: how its elements come in beside what they are drawn from. ### nodes Boxes of 116 by 44, 28 apart: six fit the drawing (124 by 72, 22 apart, as subject). The value's half is raised, the number in mono 25 (45); the pointer's half, 48 wide, is the well, with a 10-unit square the arrow leaves from. Arrows 3 wide in the ink of the region pointed into, head 12 by 10; null is a 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 the step touches: five beside, seven as subject, five in a [`loupe`](#loupe), the region whole (to 32 rows round what the step touched) on the map. Rows in address order. Tag: `its bytes`, then what the bytes are and where (`the heap, 28b41050 to 28b410bf`; `pBuf: page 2 of t.db, at rsi`), and the legend of runs: each field's name in its bytes' ink, `malloc's`, `never read`. Its runs come one of two ways. - **Typed**: from the types of what the program's pointers reach, as the `nodes` and `array` lenses have them: a field of a struct, an element of an array, the allocator's words between. - **`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`, 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 meaning is the file's and not the C's (an SQLite page). **`more`.** Rows that hold no field (a dump by `fields`), or a gap in the addresses (a typed one), are one row: at the address column, `more`'s arrow and three dots, then the count of rows it stands for in faint mono 20: `→ … 253 rows`. When the rows that hold fields are more than the window, the window is kept round the rows the step or the caption is on, and the field rows left out are `more` rows too, with their count: never cut off at the panel's edge. **What a stop saw.** `seen`: of memory nothing watches, the part the stop shown read (a debugger reads 32 bytes where a pointer leads); the rest is `unread`, whatever an older stop saw there. `given`: the bytes a system call was handed or filled, from the recording's capture of the call, as the kernel took them. They come in over what the stop saw while the kernel's work runs: dots to digits, 12 f, no strike (a value that was always there, now known), the run framed as read while the kernel takes it; at the next stop the program's own memory is shown again. **Marks** are for changes the viewer could have seen: a dump that comes in after the step that changed it, or a window that faded to a new place ([`continue`](#6-verbs)), arrives with its values plain. ### array Cells in a row, an element a cell (80 by 44 beside, 96 by 72 as subject), the index over each in faint, the variables that index it (`i`, `j`) as `under` pins. Its dump's runs are its element's type. A swap is two flights: each value lifts as a card (1.12 of the cell, 6 units off it), one flies over and one under, on an arc a quarter as high as it is long, 34 at least and 120 at most, and never past the drawing's lanes: an arc that does not fit is lowered until it does. In flight a card is over the cells and under every name and pin, which stay legible through it. ### calls The calls of one function as a tree under its caller, laid out for the whole run so that a node is where it will always be from the moment it appears: leaves in call order, a parent over the middle of its children. | Part | Drawn | | --- | --- | | node | a disc 48 across; its argument in mono 25 at its centre, primary | | levels | 46 apart, the root's centre 48 under the tag; leaves spread over the drawing's width, the last leaf's centre at 880 − 69 so its badge stays 12 inside the rule (about 111 apart for eight) | | result | on its shoulder (12 right of the centre, 42 up): a square of 30 framed 2 in faint, the number in mono 25 primary; struck when the call returns | | edge | 3 wide, centre to centre, under the nodes; primary on the path of calls waiting, rule elsewhere | | the caller | `main`, a raised box 64 by 28 left of the root on its level, the name in mono 20; an edge into the root | States, as marks: `current` (the call running) is a gold disc, its argument bold in ink; waiting (it called, and waits) a page disc in a 3-unit primary ring; done a raised disc; not yet made, nothing. The caller is a node too: gold until the first call, then waiting. So the band is never empty: before the first call it holds the caller, gold, with the backtrace beside it. Its view is the [`backtrace`](#backtrace): the waiting path read as rows, `#0` the gold node. Each node is also the `call` span of its frame on the stack, and the two are tied twice: by digits (`fib(4)` beside the span, `4` on the node) and, on the step that makes or ends the call, by a [`projection`](#4-ties) from the frame's return address to the node. **A larger tree.** The leaves share the drawing's width less the caller's box: about 680 units between the first leaf's centre and the last's. A leaf needs its disc and the result on its shoulder, and 6 between: 72 at full size (24 left of its centre, 42 right), 54 small (18 left, 30 right). | The run's tree | Drawn | | --- | --- | | up to 10 leaves, 5 levels (fib(5): 8 and 5) | full: discs 48, levels 46, badge 30 at 12 right and 42 up, mono 25 | | up to 13 leaves, 6 levels (fib(6): 13 and 6) | small: discs 36, levels 38, the root's centre 60 under the tag, badge 24 at 6 right and 32 up, argument and result in mono 20 (the floor), edges 3 | | more | small, and folded: when a call returns and the tree laid out for the whole run would need more than 13 leaves or 6 levels, finished subtrees fold, deepest first, until it fits | A **fold** is a finished call standing for its whole subtree: a done disc with its result on its shoulder and under it, faint mono 20, how many calls it hides, `+12`. It folds 18 f after its result is struck: its children glide into it (18 f, `glide`), then the tree is laid out again with it as a leaf and every node that moves glides to its new place (18 f). A path deeper than six levels keeps its top three and its newest three, the levels between drawn as one dashed edge (12 on 8) with the count of calls on it, `… 9 calls`. Both are `more` for a tree: what is left out is counted, never dropped. ### syscalls 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`, and it changes with the crossing, never in one frame: the last call's bytes go (12 f) and this one's come (12 f) while its arguments are framed (a path or a buffer handed in is there whole; one the kernel fills is dots until its bytes strike, 144 to 176); they leave when the log takes the call's row. 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 [`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 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 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 log takes them, oldest first, 2 f apart, each fading in; no lane, no kernel window, no bytes. ### loupe The telescope's other form. A `chain` on a row says, flat, `rdi → 1004070 ◂ 9`; a **loupe** opens the place it points to: a panel floating over the context with the memory round the target, the pointed thing framed, read by its type where the recording has one. A pointer in it can open the next, and a chain becomes panels in depth. | Part | Drawn | | --- | --- | | panel | 880 wide, a tag and five `bytes` rows (152 high): the target's row in the middle, two before and two after (80 bytes), its runs typed (a node's value and next, malloc's words) or by `fields`. On the map it has nine rows (144 bytes), as everything there is longer | | tag | `rdi → 1004070`, mono 20, the pointer it opens from and the target in its region's ink; ranged right, the region and the type, `heap · struct node, 16 bytes`, Go 18 dim | | target | its run or its struct framed as `attention`: 2 units, bright | | lift | its surface `lift` (`121c52`), its tag `22317a`, a 2-unit `dim` frame, and under it a solid shadow (`shade`) 12 right and 16 down; a loupe opened from a loupe, 20 and 26. This is the one place in canim with elevation: a loupe is not a panel of the frame but held over it | | stem | the tie from the pointer to the loupe: a `link` (3 units, the target's region ink, head 10 on the loupe's tag), leaving the pointer where its row has room after the chain, or from a 3-unit bracket under a pointer inside a loupe | **Where it floats.** In the working frame it hangs from its pointer: its tag's top on the foot of the pointer's row, its left edge 92 left of the pointer's digits (so the tag's address sits under them), clamped to the stage, and a 4-unit bracket under the digits lying on the tag: the stem, as short as a stem can be; it covers the rows under its pointer, whole. A loupe opened from a loupe hangs the same way from its field, 120 to the right, over the older one's lower rows. It never covers its own pointer, the current marks (the pc's row, the current line, rip's row), the ends of a drawn tie, or a row the step changes, at any moment of the step; where the first place would, it moves down past them, then to the other side; it stays inside the stage. **One hung from the band's view** (a row of the drawing's bytes) never lies over the registers, which every step changes: it lies over the stack, its tag's top on the stack's first row (clamped to the stage: in `subject` 736 to 888), its left edge on the state column's, its stem down the gutter's right lane (x 962) from the foot of its row to the tag. Where the step changes a word of the stack under it, it does not open in that step. On the map it is a panel of its own beside the memory it shows (the map has room), and on the minimap a lifted box there, its target's row outlined in its region's ink. **How many.** Two at most. A third, followed from the second, closes the first as it opens, so a chain of any length is walked two loupes at a time. While two are open their stems are two of the frame's three lines (the thread is the third): that step draws no other link and no projection. **When the flat chain is right.** Always, as the standing form: every register, slot and annotation keeps its chain, and a loupe never replaces one. A loupe opens on a beat the narration names (a pointer followed, a struct handed to a call) for a step or two; not at a run or a sprint; not where the recording holds less than its nine rows round the target. It opens and closes by its verbs ([`open`, `close`](#6-verbs)). Mocks 19 and 21. ## 4. Ties The panes are one machine at different levels. A tie says which thing in one pane a thing in another is. | Tie | Says | Between | When | Form | | --- | --- | --- | --- | --- | | `thread` | this line is these instructions, and the machine is here | the source's current line; every run of its instructions in the disassembly | standing; moves with the current mark | gold, 3 units: a `tie` bracket on the line, one on each run, a line in the left margin (x 54) between them. On the map, where source and disassembly are side by side, across their gutter (x 1008) | | `link` | this register now points at that; these bytes are there | the `reg` just struck; the row or node whose address it holds. In the introduction, a dump's rows and their place in [`segments`](#segments) | for the step that set it; a dump's place stands while both are on screen | 3 units, in the ink of the region pointed into, head on the target; ends in the target's `pin` and leaves it behind. From a dump, from a `tie` bracket on its rows | | `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; or the return address of a frame made or ended, on the stack; the part of the drawing made of them (a node's address, a cell, a call's node) | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket at the part (over a node's address; under a call's node); and the mark itself on the run and on the part | | `echo` | these are one event | the same mark at the same instant in two panels: the annotation's address and the dump's run | for that step | no line | | ink, digits | these are one thing | an address anywhere and its row, node or name; a call's arguments on its span, its backtrace row and its node | always | no line | `call` spans and `pin`s are ties too, the kind that need no line because they sit on their target. The calls lens needed no fifth tie: a frame's return address is the bytes the call left in memory, and the node is the part of the drawing made of them, which is what a projection says. A node and its frame are also tied by digits, standing, through the arguments on the span. **Budget.** One `thread`, always. For a step, one `link` and one `projection`, or the stems of two [`loupe`s](#loupe) (a stem is a link). Never more than three drawn lines in the frame; a second pointer or a second run in the same step gets `echo` and pins. rsp never takes a link: its pin is on the window's top row by construction. [`establish`](#6-verbs) draws no lines. **Off the window.** A link whose target is outside its panel's window (a slot past the stack's last row) comes down its lane to the panel's nearest row, turns into the pin lane and ends on the panel's rule: a head 9 by 12 pointing out of the panel, and beside it in faint mono 20 how far the target is, `12 rows`. The pin is drawn when the window reaches it. **Routes.** A tie runs only in channels, with corners of radius 8 (6 for a projection): | Channel | Carries | | --- | --- | | the left margin, x 54 | the thread | | the gutter's left lane, x 950 | what climbs into the band from the state column: a link from a register to a pin under a node; a projection from a frame's return address to its call node | | the gutter's right lane, x 962 | what keeps to its own height or goes down: a projection from the band's view to the drawing; a link from a register down to a slot | | 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 below; the view's projections keep to the band in the right lane and arrive from above. A link down to a slot takes the right lane under the band and ends above the frame's return address, where a calls projection leaves for the left lane: so the ties of one step cannot cross. A tie may cross a panel's rule; it never crosses a letter, a digit or another tie. A projection climbing to a call node crosses no edge: under a node that has just been made there is only room for its own children. The map draws the thread and no other tie: a link or a projection is a step's, and steps are told in the working frame. **Order.** A tie arrives before the thing it points to reacts: see [`link` and `project`](#6-verbs). Mock 9 shows the standing ties; 10 and 11 all four; 12 the projection to a call; 21 a loupe's stem. ## 5. The frame The working frame: where a scene is told. | Band | y | | | --- | --- | --- | | margin | 0 to 48 | page | | stage | 48 to 888 | 840: the lens band and the two columns | | clock | 898 to 902 | | | caption | 912 to 1032; the minimap at its right end, 1664 to 1856 by 912 to 1020 | | | margin | 1032 to 1080 | page | No data below 888 but the minimap, which the narration never depends on: a player's controls may cover its foot. **The program column** (left): source over disassembly: what was written, what runs. **The state column** (right): registers over stack: what they act on. **The lens band** (top): what it means, over the program column, and the pane that means it, over the state column. The split is the one thing about the layout a scene chooses. | Split | Drawing | Its view | Source | Disassembly | Registers | Stack | Backtrace | | --- | --- | --- | --- | --- | --- | --- | --- | | `none` | | | 14 lines, 48 to 416 | 17, 428 to 868 | 48 to 488 | 8, 500 to 724 | 4, 736 to 864 | | `beside` | 152, 48 to 200 | 152, 48 to 200: 5 rows | 8 lines, 212 to 436 | 17, 448 to 888 | 212 to 652 | 8, 664 to 888 | in the stack | | `subject` | 296, 48 to 344 | 200, 48 to 248: 7 rows | 10 lines, 356 to 628 | 9, 640 to 888 | 260 to 700 | 6, 712 to 888 | in the stack; the view of `calls` | Each panel is a window onto a column of the [map](#the-map-and-the-minimap), and the minimap shows where. **What gave** for seventeen instructions: a lens, the whole of a function and seventeen instructions do not fit one column of 840. So the lens left the program column for a band of its own; the backtrace became spans on the stack; the flags moved into rip's row; a panel's padding went from 6 to 4; and beside a lens the source shows eight lines. As the subject the drawing takes eight rows from the disassembly, the source gets two back, and the view stops two rows short of the drawing so that the stack keeps six slots. With a lens open the source is a window of eight or ten lines on the file: the map holds the rest, and the minimap shows it. | Of the frame | `none` | `beside` | `subject` | | --- | --- | --- | --- | | context | 68% | 56% | 48% | | 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. ### segments The address space to true scale, for its size, and each end enlarged once until its parts can be named. High addresses on top, as the textbook draws it; 0 at the foot. No rulers: the whole's two ends and the edges of every named band carry their addresses, and the bands their sizes. | Part | Drawn | | --- | --- | | the whole | the user half, `0` to `7fffffffffff`, in a bar 20 wide the stage's height (mock 34: 72 to 864), framed 2 in `dim`. Its ends' addresses and its size (`128 TiB`, at its middle) in mono 20 `dim`, ranged right 12 left of it; nothing else. Every mapping is where it is, which at this scale is a 2-unit line in its ink inside one end: the stack, then the libraries 128 MiB under it, at the top; the heap over the program, 16 MiB above 0, at the foot | | a cluster | the mappings at one place: the stack; the libraries (libc, ld.so, its cache, the vDSO); the program and its heap. Each is enlarged once, and only once | | an enlargement | the cluster from its lowest start to its highest end, linear: a box 180 wide (108 in a column of 880), framed 2 in `dim`, 2 out; the boxes' left edges on one x, in address order down the stage, about 48 apart, each as tall as its names need (mock 34: the stack 72, the libraries 368, the program and its heap 252). A mapping is a band in its ink 30% over the page; touching mappings of one file and one permission are one band; between two bands of one file a 2-unit page line where both are 6 tall. What is not mapped is page: the 1.3 MiB between libc and the loader is as empty in the box as it is in the process | | the magnification | two 2-unit `rule` lines from the cluster's line on the whole (at its right edge) to the box's left corners. Nothing else is drawn between the whole and the boxes | | the names | right of the box, from 64 past it (the leaders' room). A row for each edge of a named band: its address in mono 20, in the ink of the band it bounds, and a leader (2, `rule`) from the edge, 8 out, straight to 20 short of the address, 12 in. Between two edges a row for the band, indented 24: its permissions and its size (`dim`, ranged right 132 in), and its file in primary at 252 (`[stack]`, `libc.so.6`); a file of several named bands once, on a `quiet` bracket over their rows. Rows 24 apart, each as near its edge as the others let it (crowded rows pooled round their mean), inside the box's share of the stage; a leader never crosses another, as the rows keep the edges' order | | what is named | the program by segment: each of its mappings a band with its two addresses, permissions and size, under a bracket with its name, because the scenes point into them (its code, its data). Every other file once: its mappings as one (an anonymous mapping after a file's data, its bss, with it; the vDSO with its data), its start, stop, size and name, its permissions where they are one (`rw-` for the stack and the heap), and where they differ, each part's written inside its band, centred, where the band is 28 tall. A band under 6 tall is drawn and not named (an anonymous page; in mock 34 the vDSO) | | live | rsp an `under` pin in the stack's band; rip a row pin at the end of its band's row (`◂ rip`). In the introduction's first chapter neither: there are no registers yet | | a dump's place | in the introduction, where the dump the scene has built stands beside it: a `tie` bracket on the dump's rows, and a [`link`](#4-ties) in the stack's ink from the bracket's top, up into the stage's top margin (y 56), across, and down onto the stack's box at the dump's address, its head on it. It draws in its own beat and then stands, quiet (60% toward the page), while both are on screen | | `ink`'s echo | the band a word points into, framed as read inside the box (2 units, 4 in from its sides, 6 over and under the band), and that band's row of names framed with it | The physical comparison is the caption's, worked from the recording: if the bar were the Eiffel Tower (330 m), everything mapped would be 7 µm, a tenth of a hair, split between its two ends; the introduction's 128 bytes would be 0.3 nm, about an atom. Three treatments say less and less (mock 35): **A**, this (mock 34); **B**, every file once, the program too, and no pins; **C**, the whole alone, each cluster one label at its end (where it starts, its size, its name). A is the default: the program's segments are what the scenes point into, and every other file is said once. `segments` is a frame of its own (mock 34) or, in the introduction, the program column (mock 30, the boxes 108 wide). In motion each box rides out of its line along the magnification ([`enlarge`](#6-verbs)). ### aligned The source with the instructions it compiled to, in one panel with one tag, each line level with its code. A split a scene chooses, the default nowhere: the panel spans both columns (1792), the band and the state giving way while it lasts. It has two forms, and a scene names the one it wants: - **`interleaved`** (mock 33), as `objdump -S` prints it: each run of a line's instructions is a group, its head a row with the line on `raised` paper, its rows under it, indented one step under the line's text. Lines and addresses share one place column (ranged right at 196: `21` over `1001926`): both say where. - **`columns`** (mock 36): the source on the left and its instructions on the right, a 2-unit `rule` the seam, 48 after the longest line the window shows, so that the two stay close. A line stands level with the first row of its run, its cell as tall as the run, its first row on `raised` paper (the head of `interleaved`, beside its rows instead of over them). Each column begins with its place, ranged right 132 into it in mono 20: the line's number in the one, the instruction's address in the other: one slot, one face, one distance in, so the two read as the same kind of thing. In both a 2-unit `rule` across the panel over every group marks where a line's code starts and ends; nothing alternates. The grouping is the thread. | | `interleaved` | `columns` | | --- | --- | --- | | a run of one row; of many | its head and its rows, never folded in the working frame | the line beside its first row, its cell as tall as the run | | a line's second run (a `for`'s step, a `while` tested again after its body) | its head again, on the page, faint, `again: its second run` | the line again in its cell, on the page, faint, `again: its second run` | | rows of no line (padding, a function without source) | a faint head with the function's name, `_init · no line` | the cell empty but for `_init · no line`, faint | | a line with no code of its own | no group: the gap in the numbers says so | in source order after the line before it, faint, the instruction cell empty, `no code of their own` on the first of a run of them: the source column reads as the file does | | the pc | its row's wash and plaque; its line's number the gold plaque in its head | its row's wash and plaque in the instruction column, the wash across both where it is its line's first row; its line's number the gold plaque | `interleaved` reads down one listing and puts each instruction right under its line; `columns` keeps the source readable as source, at the cost of an empty cell under a long run. Reach for either to teach what a line compiles to, in the introduction, and in a pair (a `pair` puts the source in the middle and each build's rows aligned to it on its side). `align` and `stack` change between `aligned` and the stacked form, and between its two forms; it scrolls as one. Mocks 32, 33 and 36. ### pair Two runs of one program seen against each other: two builds (plain and with AddressSanitizer), two versions, two C libraries, two inputs. It is a split of the working frame, and general: the shared panels are drawn once, the ones that differ twice, one on each side of a seam. | Of the frame | Drawn | | --- | --- | | the seam | the gutter between the columns (944 to 976): the left column is one run, the right the other, each panel's tag naming its run (`plain · disassembly`, `asan · disassembly`). Down is still deeper in each; across the seam is the other run | | the source | shared when both runs are the same file: one panel across both columns, 1792 wide, five lines (48 to 200). Each run's current line is marked on its own side of it: the left run's gold plaque on the number at the left, the right run's ranged right at the panel's right edge, the wash across the row once when both are on it. Two files: two panels, as below | | each column | its run's context cut to what the scene's line touches: its disassembly, nine rows (212 to 460); the registers the line reads or writes and rip, rsp, rbp, four rows (472 to 600); the stack frame from rsp to the return address, ten rows (612 to 884). A run built with ASan adds the shadow to its stack's rows ([`slot`](#slot)) | | alignment | the two disassemblies are scrolled so that the current line's first row is at one height on both; below it each runs on. The two stacks are scrolled so that the same variable's first row (`buf`) is at one height. Corresponding things face each other across the seam | | only here | a row one run has and the other has not (the instrumentation; a function only one build calls): a 4-unit `dim` bar on its seam-side edge. Its counterpart is the page facing it, or nothing | | differs | a value that differs from its counterpart at the same step (the saved rbp kept on one side and overwritten on the other): a 4-unit `bright` bar on its seam-side edge, on both sides. It is the difference across runs; a strike is a change in time, and both can stand together | | the clock | one rule, counting the pair's steps; under it, ranged right, each run's moment: `plain moment 61 · asan moment 412` | | the caption | one, for the pair: it narrates the difference | | the minimap | both runs' maps at a fortieth, side by side in its box (96 by 54 each), each with its windows. The map itself is one run's at a time: a `surface` goes to the side in focus | **Keeping the two in step.** A pair's step is one source line in both runs, or one turn of a loop when the narration says so: the unit both share. Inside it each side walks its own instructions; their cascades share the levels (CPU, memory, the idea), and the side with more rows sets the step's length, its rows 6 f apart, the other side's spread over the same time. Its first time through, a row only one run has (ASan's check before a store) is walked row by row as any step, the other side holding still with its plaque on the row that faces it; after that, at a run inside the step. When one run stops (a report, a crash, an exit) and the other goes on, the stopped side holds its last picture, unveiled, and the steps go on in the other alone. **When they part** is the scene's point: the first step in which the two runs do different things (one stores, the other branches to a report). That step is walked; its two sides' first different rows are framed `attention`, one each side, and nothing else moves until both have struck. A run that writes to stderr (ASan's report) shows it in its own column, in place of its registers and its disassembly's lower rows once it has stopped: a panel of the run's output, its lines as written, the ones the narration names framed. Mocks 26 to 28; [the scene](motion.md#a-scene-asan-against-a-plain-build). ### The map and the minimap **The map** is the working frame unfolded: every panel at its full length, on a stage of 3840 by 2160 units (sides 112, top 96, the stage 3616 by 1688), at the context's type size. It is one picture of the program at a moment: the whole of a short file, the function round the pc and its neighbours, all seventeen registers, the whole backtrace, the stack from 16 words above rsp to its top, the regions the scene's steps touch, the lens's drawing, and the loupes open. - **Columns by content.** Four columns of 880, 32 apart, in the working frame's order: the drawing and the program's panels in the first two, the state's in the last two. Panels are packed: each as long as its content (a file of 42 lines is 42 rows, a backtrace of five frames five), the next under it with 12 between; a panel longer than what is left of its column continues at the top of the next column's free space, as a second column of itself under the same tag, `continued`. Nothing is stretched and nothing is centred to fill. **A box is as tall as its rows, never taller**: a dump is the rows that hold a field or were touched, with `more` rows for the rest, so a region with six rows of fields is a box of six (176 units), not a window of 32. Space a column has left is given, in this order, to: more of the stack (before it folds into `more`); the memory round the pointers the registers and the stack's words hold, a short dump each (five rows round the target, its region's ink, under the memory panel); the loupes open; and last the map's key (the scene, the moment, the marks' legend, three rows). Only then is a column's foot page. - **Its lengths.** The source: the file whole, or 69 lines round the current line. The disassembly: 69 rows, the function whole where it fits. The stack: from 16 words above rsp (the 128 bytes the recording keeps under it) to the stack's top, folded into `more` after the process's start. Memory: each region the scene touches, up to 32 rows round what was touched, as many as hold something, fieldless rows folded. The drawing: its subject size, 880 by 296. A loupe: nine rows, beside the memory it shows. - **What it draws.** The rows as the working frame draws them, the marks of the moment (current, struck, read, held, trail), the thread across the gutter between source and disassembly, and an outline round each of the working frame's windows: a 2-unit `dim` frame, 4 out. No link and no projection: a step's ties are the working frame's. - **What reads where.** In a 4K export the map filling the frame is 20 pixels to a row's text and reads; at 1440p 13 and reads on a monitor; at 1080p 10, a texture of shapes and inks in which the windows, the gold rows and the vermilion of a write are what is seen. The caption carries it there, and the map is never on screen for reading at 1080p: it is for where, not for what. **The minimap** is the map at a twentieth, 192 by 108, in the working frame's corner: the caption band's right end, 1664 to 1856 across and 912 to 1020 down, under the clock's right end. The caption keeps its 1400 (it ends at 1464); the clock's count moves left of the minimap, ranged right at 1648. | Part | Drawn | | --- | --- | | ground | the page, framed 1 in `rule` | | panels | each map panel's outline, 1 in `rule`; a lens's drawing a `raised` block; a loupe a `lift` block | | rows | each row of text a stroke 1 high, from where its text starts as long as it is (a twentieth of its characters' width), in its dominant ink at 45% toward the page: the file's shape, the stack's chains, a dump's bytes | | windows | each working panel's window, 1 in primary, the panel in focus 2 | | marks | the current row a gold stroke across its column, 2 high; a strike a vermilion block 3 by 3 at the row's start; a read a 3 by 3 frame in read's colour; held a vermilion pixel; the thread a gold stroke across the gutter | A mark outside every window is on the minimap and nowhere else: when the step strikes a word the stack's window does not show, its block on the minimap strikes with it, and `flash`es (a ring 8 across drawing out to 14 and gone, 12 f) so the eye goes there once. That is how nothing is hidden at the working frame's size: it is only small. The minimap is secondary action: every change on it starts 6 f after the primary onset it follows, never on that frame; it fades and never travels, except its windows, which glide with their scrolls. ### clock and caption - **`clock`**: a 2-unit rule the width of the stage at y 900; gold, 4 high, along it as far as the recording has run; `moment 72 of 95` in mono 20, faint, ranged right at 1648, left of the minimap. It says where the recording is, so at a walk and a run it is still while a step plays: when the step's mark has landed, the step's piece of gold fades in (12 f; 8 f at a run) and the count changes as the fade starts. At a sprint the gold grows with the recording, linearly, and is the one thing that says "fast". - **`caption`**: one or two lines of at most 64 characters, Go 40 on 54, ranged left on the margin; code in it is mono 35. Hex in it is unbroken too. What a scene author checks, characters counted as shown: | Rule | Number | | --- | --- | | on screen, from arrived to leaving | at least 1.5 s + 0.06 s a character (90 f + 3.6 f) | | on screen | at most 12 s; a longer stretch wants a second caption or a shorter scene | | before the first step it describes fires | 60 f after it has arrived; 120 f for a scene's first | | a scene's first | arrives at 1.0 s; the first step fires by 4.0 s (5.0 s when the scene opens on the map and dives) | | changes | only in a rest, never under a moving thing | | names | only what is on screen at the pace it plays: no register a run veils, no step that has not happened or that played more than its 60 f lead ago | | checked | by the instruments' CAPTION ([motion.md](motion.md#the-instruments)) | | longer than two lines | two captions, split at a phrase rest | | the last | its reading time before the cut, and 2 s on the finished picture; the scene grows to fit | - **`veil`**: the page at 50% over the panels a named beat does not touch, and over what a pace cannot show ([`run`, `sprint`](#6-verbs)); at 65% under the camera. In over 18 f, out over 18 f. - **`card`**: a title or the legend ([mock 6](mock/06-title-legend.png)). The only frames with no context. - **Camera rests**: x1 (the frame), x1.5 (1195 by 560: a column, or the band), x2 (896 by 420: sixteen rows), x4 (448 by 210: one chain). It is for reading, and always comes back. ## 6. Verbs Frames at 60 a second. `s` is the frame a strike lands. Curves: `standard` (0.3, 0, 0.2, 1) for things arriving; `glide` (0.45, 0, 0.55, 1) for things travelling and cooling. Charts: [`motion.md`](motion.md). | Verb | On | Chart | | --- | --- | --- | | `fire` | the current plaque | 0 to 12: it pulses once. Nothing else moves | | `arm` | a value about to be written | s-12 to s: the `armed` frame, in over 2 f; the old value still in it | | `strike` | a value written (in a dump, its bytes from the first that changed to the last, 1 f apart; never the whole field) | s to s+6 the fill comes in, linear; the new digits at s+3; s to s+12 its edges go out 3 units (4 in a lens's cell) and back, sine; solid until the advance | | `cool` | a struck value | starts with the advance: 24 f, `glide`, the paper to nothing, and the turned corner of `held` fades in over its last 6 f, for three steps (then out over 36 f); the same in a lens's cell. The digits go to their ordinary face at its middle | | `read` | a value read | in over 6 f; held to the advance; out over 18 f. No arm, no pulse | | `extend` | a chain whose first hop was struck | each later hop is followed again, 4 f apart, fading in over 6 f | | `link` | a `reg` just struck, and its target | s+6: the old pin fades (12 f) and the line draws from the register's row, head first, 24 f (36 f over 400 units), `standard`, the pin riding its head; the pin lands with the head and settles (12 f); held; at the advance the line draws back into the pin over 18 f. A target out of the window: the line ends in its stub, and the pin waits for the window | | `project` | a run read or struck, and its part of the drawing | on the run's mark: the bracket on the row (6 f), the line draws from the bytes to the drawing (18 f; 30 f over 600 units; `standard`); only when it arrives does the part react (its own `read`, or `arm` and `strike`; a new call's node fades in, 6 f); out with the advance, 18 f | | `travel` | a value, a card or a pin going from one place to another | `glide`. A value or card: 30 f to 200 units, 36 f to 400, 48 f beyond. A pin goes along its lane, 18 f after the strike that moved it: in a drawing 30 f to the next node or cell, 36 f to one farther; in the stack's lane 24 f to the next row and 2 f a further row, 36 f at most. A pin that comes fades in over 12 f rising 8 units; one that goes fades out over 12 f; a name joining or leaving a pin cross-fades over 12 f. On a `link` the pin rides the line's head instead. 8 f at a run; at a sprint only at a phrase's end | | `open` | a loupe, from a pointer | the pointer's hop framed `read` (6 f); the stem draws from it to the loupe's place, head first, 18 f (30 f over 600 units), `standard`; the loupe rises with the stem's head: it fades in over 12 f from 8 units lower, its shadow growing from nothing to its offset (18 f, `standard`); the target's bright frame lands 6 f after. From a pointer inside a loupe the same, over it, and a third closes the first as it starts. In the slot of the level that read the pointer, or on a beat the caption names | | `close` | a loupe | the deepest first: its stem draws back into its pointer (12 f) and the loupe sinks, fading out over 12 f as it falls 8 units and its shadow shrinks; with the advance of the step it opened in. A loupe the narration keeps across steps closes at each advance and opens again in the idea's slot of the next step that concerns it (36 f, as `open`): the steps between are not drawn under it. Open 120 f without a change is the most | | `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 rect (1664, 912, 192 by 108), continuously, its scale from a half to a twentieth on its logarithm, so the windows rise out of it as it falls away; it is never dropped or hidden on the way; their outlines stay on it and land as the minimap's windows; as it lands (90 to 96) it crossfades into the minimap's own drawing. 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 the caller's window closes round its call row, in two moves and never both at once: 66 to 78 the rows it gives up fade (those after its return row, and from its top as many as the callee needs), then 78 to 96 the rows it keeps glide up to their places (`glide`), where they move at all; 84 to 96 the call row's plaque becomes the ring; 96 to 114 the call lane draws down from the ring, head first, `standard`; 108 to 120 the callee's head fades in rising 8 as the lane reaches it; 114 to 138 its rows, top down, 2 f apart, 12 f each; 138 to 150 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 other rows fade (12 f), then its `jmp` row, `pass`, glides to its place (18 f, `glide`), the lane runs on to the next head (18 f), the next window comes in the same way. A label that changes with it (the stack span's name, the source's tag) crossfades, 12 f | | `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; the caller's window opens in the reverse order of its closing: 84 to 102 the rows it kept glide back down (`glide`), then 102 to 114 the rows it gave up fade in; 114 to 126 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` | | `leave` | a block of a graph, along an edge | 0 to 12 fire on its last row; a conditional's compare row has its chips framed as read (18 to 24): the cause; 24 to 42 the edge it takes draws gold (3 units) from the port to the target, head first, `standard`; then the mark travels it: the gold plaque leaves the row along the edge, `glide`, 12 f and 2 f a 100 units, 30 f at most, the row cooling to the trail as it goes; it lands on the target's first row (the advance) and 6 f after, the target's count is armed and struck; with the landing the oldest of the three trail edges cools to `dim` (18 f). A fall-through leaves the same way. At a walk, 1.5 s | | `turn` | a loop's back edge | `leave` along the lane: out of the bottom, out to the lane, up it, in at the header's head; the lane's count struck as the mark goes in | | `spread` | the rows into a graph (on the map, or in a `dive` or `surface` between a graph and the working frame's rows) | 0 to 36 every row glides from its place in the column to its place in its block, `glide`, the blocks 4 f apart in layer order; nothing fades while rows travel; 36 to 48 the blocks' frames and heads fade in round them; 48 to 72 the edges draw, layer by layer, 2 f apart, 12 f each. `gather` is the reverse: edges out (12 f), frames and heads out (12 f), then the rows glide home (36 f) | | `regroup` | bytes into a word (the introduction) | walked, on one word ([chart](motion.md#a-word-read), mock 37): the dump goes from sixteen bytes a row to eight (each right half down a row, then left); the other rows are veiled; the word's offsets fade in under its bytes, `low byte` under the first, `high byte` under the last; then the bytes themselves fly, the low byte first, 6 f apart, 36 f each, `glide`: straight up, over on nested arcs a quarter as high as they are long (34 to 120), straight down onto their pair's place in the word's field, 30 apart and ranged right, so that they land reversed, each offset and label going with its byte, and a faint copy fading into each one's place in the dump once it has left; the gaps close to sixteen digits (12 f); the zeros in front are bracketed, `zeros in front`, and fade (12 f). At a run (the other fifteen): each row's word fades in (8 f) as its bytes dim, rows 6 f apart. The word field is eight pairs wide, so a word is always ranged right, its low byte last | | `ink` | a word becoming an address | its digits go from primary to its region's ink (12 f), and the band it points into in `segments` is framed as read inside its box, with the band's row of names (6 f): an echo, no line. The first walked, held 60 f; the rest at a run, 2 f apart, each band framed 12 f | | `enlarge` | a box of `segments`, out of its line on the whole | 0 to 6 the cluster's line on the whole framed bright; 6 to 78, `glide`, the box rides out along the magnification: its left corners travel the two lines from the line to their places, the lines drawn behind them, the box as tall as they are apart and as wide as the ride is far (the bar's 20 to its 180), its bands drawn at its scale all the way (a mapping a 2-unit line until it is taller; the gaps opening); 78 to 90 its page lines fade in and the frame on the line goes; then its names, rows top down, 2 f apart: an edge's leader draws from the box (6 f), then its address fades in (12 f); a band's row fades in (12 f). The clusters in address order, each riding out as the one before lands ([chart](motion.md#the-address-space-enlarged)) | | `column` | rows gaining a column (offsets, roles, pins, lines) | the rows make room (18 f, as rows do), then the column's values fade in top down, 2 f apart, 12 f each | | `frame up` | a panel arriving round rows already built | its rule draws round them (12 f), then its tag fades in (12 f): the last thing, never the first | | `decode` | an instruction's bytes becoming its row | the bytes of one instruction gather (12 f), the mnemonic and operands fade in beside them (12 f), and the bytes dim; the row then travels to its place (`glide`, 24 f) | | `align` | the stacked program column to `aligned`, and back (`stack`); one form of `aligned` to the other | the band and the state column fade out (12 f); the panel widens to both columns (24 f, `glide`); the source's lines glide to their heads and the instructions glide in under them (36 f, rows making room), each instruction from its row in the disassembly to its row under its line; the heads' paper and rules fade in last (12 f). `stack` is the reverse. `interleaved` to `columns`: the addresses and instructions glide right into the instruction column (24 f, `glide`), then every row glides to its height in the new form, each line level with its run's first row (24 f, `glide`); the rules move with their groups; the lines with no code fade into the room made for them (12 f). Back, the same in reverse, the no-code lines first | | `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 | | `continue` | a stop far from the last: a breakpoint, not a step. Where the windows' new places are farther than their own heights (another function, another file), it is told on the map: `surface`, the jump there, `dive` | `fire` on the line it leaves from; then the levels as in a `cascade`, but CPU is a wave: every register that changed is struck 2 f after the one above it, in pwndbg's order, the fill in over 6 f, no arm and no pulse (a dozen pulses at once are a flash, and a dozen arms a crowd); memory: the stack's window scrolls or fades to its new place, and the [backtrace](#backtrace)'s frames leave, slide and arrive; the idea; hold 36 f after the last strike; `advance`, the source and disassembly fading through if far; rest. Its marks are only on what was on screen to change | | `run` | steps that need not be read | over a graph, the mark goes from block to block in 8 f, each edge taken flashes to gold and cools in 8 f, counts change in place; at a sprint (on the map) the gold moves only when the block changes, 4 f at most each, the trail's three edges following and the lanes' counts ticking, and the picture settles at the phrase's end. Elsewhere: 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; no strikes, no held corners and no arcs drawing: a value changes in place under an 8 f crossfade, unmarked, and what the run changed is shown settled when it ends (its arcs fade in, 8 f, standing; no corners); no ties but the thread. A caption never names what a run veils. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most. A run longer than a phrase may `surface` and play on the map | | `sprint` | steps to be got through | 4 f a step. The drawing grows and the clock sweeps; the source and the band's view are veiled as well; the mark and the pins move only at a phrase's end. Each change of pace ramps at 0.6 of the step before. A sprint plays on the map: `surface` before it, `dive` after it, at the stop it reaches; the windows glide with the pc, the minimap's marks flash and fade | | `establish` | a scene's opening | done by 54 f: the panels fade in, 18 f each, 6 f apart (registers, stack, source, disassembly, the band's view, the drawing's panel: 0 to 48); from 30 f the drawing's elements fade in rising 8 units, 12 f each, 2 f apart in address order and all begun by 42 f, each with its row's quiet bracket (an `echo`: no lines). The first caption arrives at 60 f | | `scroll` | a `source`, `disasm` or `stack` window | whole rows, 24 f, `glide`, before the level it makes room for; marks ride with their rows; the window's outline on the minimap glides with it, the same 24 f. A column's `lead` and the line numbers are the rows' on screen: they change on the scroll's first frame, never before. A window going farther than its own height (ten lines, nine instructions, six slots) does not scroll, which would only blur: it fades out (12 f) and in at its new place (12 f), and what it brings comes in with no marks | | `relayout` | a change of split | the drawing fades out (12 f); every panel moves to its new box, clipped to the box as it moves (48 f, `glide`); the drawing fades in at its new size (12 f). Nothing else moves under it | | `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`. The panel's tag and whole rows in frame, the rows the visit's steps change in its middle third, never at its edge; a stack visited holds its window still. A visit never veils or clears a panel a drawn tie starts or ends in: it waits until the tie has drawn back, or frames both ends. 120 f at most without a change; back | | `say` | the caption | out 12 f, gap 6 f, in 18 f; the numbers are under [caption](#clock-and-caption) | **Nothing changes in one frame.** A label that changes in place (a tag's note, a span's name, a box's name, the source's tag) crossfades over 12 f; a count that appears fades in (6 f) and is then armed and struck; a value written is struck; a window going far fades through. The instruments' POP finds any one-frame change after stillness. 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; 2.9 s to follow a call down, 3.6 s for a crossing (4.9 s when it moves bytes), 2.5 s back up. ## Composition **What may contain what.** - 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, 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 states are `focus` and veiled. - A tie sits over panels, in channels. It joins `place`s that blocks publish (`reg`, `slot`, a word, a node, the line, the pc); it never reads a panel's layout. - A panel is `32 + 24 n` high. Panels do not overlap and are 12 apart. **Adding a block.** 1. Name it: one word, a noun, not in the vocabulary. 2. Compose it from the layers above. If it needs a new atom, add the atom first, on its own. 3. Give its states as `mark` states. A new state needs a new form, not a new colour. 4. Publish its `place`s. 5. Give its motion in the verbs. A new verb only when no sequence of the existing ones says it. 6. Draw it in the gallery in every state, at x1 and at 480 wide. 7. Add its row to the vocabulary and to the mocks table. **Forbidden.** - Information carried by hue alone. Every ink has a second sign (a name, quotes, a position, a paper) except heap against data, which is admitted above. - A mark under coloured digits, except a strike for its 0.6 s and the gold ember of a current row. - A tie across text, or across another tie. More than three drawn ties. - Two strikes landing in the same frame. Two writes of one step are 6 f apart, in the order they happened. - An effect before its cause: a drawing changing before its bytes, a card lifting before its bytes are struck, a result stored before the kernel returns it, a current mark moving before the hold. - A mark wider than what changed: bytes struck that kept their value. - A mark on what the viewer could not have seen change: a window that faded to a new place, a panel that came in after its step. - A text scrolled farther than its window's height: it fades through. - A pin that jumps, two pins for one name, two names in one place. - A space inside a number. A row that wraps. Rows that reorder. - Anything hidden to make room: a row that cannot hold its chain ends in `more`, a panel that cannot hold its rows ends in a count, a link whose target is out of view ends in a stub and a count, a label cut short ends in `…`. - Mono under 20, sans under 18. Lines under 2 units. Dashes finer than 12 on 8 off. - Alpha tints (but the veil), gradients, glow, grain, rounded panels. - Solid vellum for anything but the kernel. Gold for anything but where execution is. ## The mocks `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/graph.py` draws the graphs (22 to 25) from `sort-O0.dis`, `reverse-O0.dis` and `libc-open.dis` and the paths their runs took; `mock/heap.py` draws the heap scene's storyboard (18) from a recording of `mock/heap.c`; `mock/intro.py` draws the introduction and its blocks (29 to 37) from the same list recording and its mappings; `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 16-descent.svg 16-descent.png resvg 17-operands.svg 17-operands.png python3 -B heap.py && for n in 18-heap 18-heap-free; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done python3 -B graph.py && for n in 22-graph-sort 23-graph-open 24-graph-strip 25-blocks-lens; do resvg $n.svg $n.png; done python3 -B pair.py && for n in 26-pair-rest 27-pair-store 28-pair-part; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done python3 -B intro.py && for n in 29-intro-bytes 30-intro-words 31-intro-stack 32-intro-code 33-aligned 34-segments \ 35-segments-abc 36-aligned-columns 37-regroup; do resvg $n.svg $n.png; done for n in 30-intro-words 34-segments 36-aligned-columns; do resvg -w 480 $n.svg $n-480.png; done python3 -B dense.py && resvg 15-marks.svg 15-marks.png python3 -B map.py && for n in 09-context 10-context-step 11-context-lens 21-loupe 19-map; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done # 20-dive.png it composes itself resvg -w 1920 19-map.svg 19-map-1080.png python3 -B gen.py # 1 to 8, then resvg the same way ``` | Mock | Is | Blocks it shows | | --- | --- | --- | | [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, 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, its spare rows above its call and one row after it, the PLT stub's head directly under that row (its neighbour `_start` `outside`), 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 of the band: `ztrace dbg` on `mock/heap.c`, glibc 2.44, after each malloc and free (2 a run's end, settled, unmarked) | `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 | | [18, the free](mock/18-heap-free.png) | beat 3 in the working frame, mid-step | the register wave a stepped-over call leaves; a `loupe` from the band's view lying over the stack, never the registers, its stem down the gutter's right lane; `rdi` still on the freed chunk; the tcache's two fields, `0x2f8 bytes` | | [22](mock/22-graph-sort.png) | the map's disassembly as sort's `graph`, two columns wide beside the source, at moment 370 of the stepped run (the sixth pass, its third compare) | blocks with heads, offsets, lines, visits; the pc's block gold with its annotations (a compare's values and flags, the `jg` reading them); the inner and outer loops' back edges climbing their lanes with their turns; a conditional's counts by its ports; the edge never taken (`jle` to the next pass) in `rule`; the right channel; a call's hook (`swap`); the exit not yet reached | | [23](mock/23-graph-open.png) | libc's `open` at its `syscall` (mock 16's moment 4): 19 blocks, the run's 8, the 11 never reached folded into five boxes by what they are | folds of unreached blocks, named; blocks the run will reach but has not yet, plain; twelve-digit heads, offsets in the rows | | [24](mock/24-graph-strip.png) | reverse's loop, four instants | `leave`: the condition's chips, the edge lit, the mark halfway along it; `turn`: the back edge climbing with the mark on it, its count struck; the way out | | [25](mock/25-blocks-lens.png) | sort at moment 370 in the working frame with the `blocks` lens | the graph as shapes in the band, the pc's box gold, the trail; its view the disassembly round the pc, out of the program column, which holds the source alone; registers and stack of the moment | | [26](mock/26-pair-rest.png) | the `pair` at the loop, i = 15: plain and ASan builds of `overflow.c` | the shared source with each run's mark on its side; two disassemblies aligned by line, ASan's `only here` rows; the line's registers; plain's stack with the red zone's `buf` and `i`, ASan's fake frame with its shadow on each word's row, `buf` facing `buf`, the saved rbp facing the redzone (`differs`) | | [27](mock/27-pair-store.png) | one turn of the loop, row by row: plain's eight instructions each facing its counterpart among ASan's seventeen | `only here` bars; the page facing the check; the check's values (`0 : 0 ZF`, `taken`); the partial check and the report's call faint, off the path at 00 | | [28](mock/28-pair-part.png) | i = 16, the step in which they part | plain's store struck into the saved rbp's low byte; ASan's shadow load framed reading `f3`, its compare and the branch not taken; `differs` on the facing rows | | [29](mock/29-intro-bytes.png) | the introduction's first picture, the camera at x2: 128 bytes of the stack, nothing else | a raw hexdump, before any ink | | [30](mock/30-intro-words.png) | the `ink` beat: the words, eight bytes a row, where the stack will be; the address space in the program column | `regroup` landed, each word ranged right; `segments` at 108 wide, no pins; a dump's place, the `link` standing; `ink`'s echo: the return address and list's code band, with its row | | [31](mock/31-intro-stack.png) | the same words as the stack panel, the registers built over it, at x1.25 | the stack's conventions: rsp and rbp pins, offsets, roles, spans | | [32](mock/32-intro-code.png) | the code chapter: `aligned` with each instruction's bytes between its address and mnemonic | an instruction as bytes, decoded, level with its line | | [33](mock/33-aligned.png) | the `aligned` split, `interleaved`: reverse and its neighbours, the pc at the load | a line with two runs (20), lines with no code, rows of no line, the band as the thread | | [34](mock/34-segments.png) | `segments` as a frame, treatment A: the list recording's mappings (`ztrace show`) | the whole with its ends and size; three boxes; the program by segment under its bracket, every other file once; addresses at the edges, sizes, permissions in a row or inside a band; leaders pooled; rsp and rip | | [35](mock/35-segments-abc.png) | the three treatments as frames, saying less and less | A as 34; B every file once; C the whole alone | | [36](mock/36-aligned-columns.png) | the `aligned` split, `columns`, on 33's data and `_init` after it | the seam after the longest line; places at each column's start; line 20's cell eight rows tall; its second run; lines 23 to 25 with no code; rows of no line; the pc's wash across both columns | | [37](mock/37-regroup.png) | `regroup` walked on the return address, `b0 18 00 01 00 00 00 00`: eight instants with their frames | the reflow to eight a row; the offsets and the low and high byte; the flight on nested arcs; landed reversed; the gaps closed; the zeros gone; the run; the ink | | [1](mock/01-fib-recursion.png) | first pass | `calls` at camera scale | | [2](mock/02-list-insert.png) | first pass | `nodes` at camera scale; `allocated` | | [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` (the kernel's side is now the descent's floor, 16) | | [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` | | [8](mock/08-far-view.png) | first pass | `pages` | Mocks 1 to 8 were drawn as whole frames before the context existed. Each is now what its lens looks like under the camera; none shows its lens in the band. **Specified, not drawn.** - The `none` split, and the `backtrace` as a panel of its own. - `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 stub off the window. A variable's pin. - The stack's window held for a visit with `free` slots. - `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`, `pages` in the band. - The heap scene's map and minimap (their 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's opens from the band's view); 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. - `enlarge` and a dump's place in motion (charts only); treatments B and C of `segments` at their own sizes (the sheet has them as frames); `align` between `interleaved` and `columns`; `columns` with a pc in a long run, away from its line's row. - A local's name as a slot's role (the recording has none at these pcs). - `pin` with a count; `rwx`. - Every verb: the mocks are stills. `establish`, `link` and `project` have no chart from a render yet. **The data in 9 to 21** is the recordings': registers, chains, stack, the instructions and their lines (12: `ztrace show` on `anim/zig-out/recordings/steps.ztrace`, lines from its binary by `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`; 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 arguments on 12's spans and rows are the calls' own, from the tree. **At 480 wide** no digit of the context reads. What is left: the layout, the gold rows and the thread, the strike on `rdi` and its link into the band, yellow and blue as texture, the caption whole. Through x264 at 720p (CRF 28) mock 10's dump, its faint padding bytes, its dots and the chains still read. ## What this asks of the renderer What the documents say and `anim/src` does not do, as read on 10 November 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. **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. **The graph** ([`graph`](#graph)): basic blocks from the recording, the layered layout (back edges by a walk from the entry, layers by the longest path, the hot path straight down, loops' lanes on the left, the right channel), blocks with heads and offset rows, the edges' ink by what the run did, folds (never reached, long blocks, finished loops), pan; on the map in place of the linear column, two columns wide; the linear form's block rules and counts; the `blocks` lens with the disassembly as its view; `leave`, `turn`, `spread`, `gather`; the run and the sprint over it. 8. **The pair** ([`pair`](#pair)): the split with a seam, the shared source with a mark per run, two columns of one run each, alignment by line and by variable, `only here` and `differs`, the shadow on an ASan run's stack rows, one clock with two moment counts, two minimaps at a fortieth, the stopped side holding, a run's stderr as a panel; steps matched by source line or loop turn. 9. **The introduction's blocks** ([`segments`](#segments), [`aligned`](#aligned)): `segments` from the mappings: the whole (a bar, its two ends' addresses and its size, every mapping a 2-unit line at its end); a box for each cluster with the two lines of its magnification; its names, a row for each edge and each band, rows 24 apart pooled round their edges, the leaders; the program by segment, every other file once, permissions in the row or inside a band 28 tall, nothing named under 6; rsp's and rip's pins; a dump's place (the bracket and the standing `link` over the stage's top); `ink`'s echo on a band and its row; treatments B and C as options. `aligned` in its two forms, `interleaved` and `columns` (the seam set by the longest line in the window, both places 132 into their columns, cells as tall as their runs, the lines with no code in source order). The verbs `regroup` (walked, and at a run), `ink`, `enlarge`, `column`, `frame up`, `decode`, `align` (also between the two forms of `aligned`). A hexdump with no ink (the first picture only), and a word field ranged right, eight pairs wide. 10. **Still from before**: the calls tree's small size and folds, `metric.span.name_max` 300, `time.caption_max` 12 s and `time.first_step` 4 s (5 s when a scene opens on the map), `time.dive` and `time.flash`. **What the recordings must hold**, with the tracer's options: - 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). - For a pair (the ASan scene): see [the scene](motion.md#a-scene-asan-against-a-plain-build). - For the introduction: the mappings with their permissions and their file offsets (to say code, read-only data, data): `ztrace show` prints them now (this round's recording of `targets/list` under `env -i setarch -R`; the kernel now splits `[vvar]` in two, `[vvar_vclock]` its second page pair); the bytes of the instructions in the window (or the binary, for the renderer to read them); and a recording of the program by instruction from `main` to the stop, so that a real `push`, a real `call` and the moment rsp moves are shown, not described. - **For the graph**, per function and once: its blocks (first and last address, how each ends: a conditional jump, a jump, an indirect jump, a return, a call that does not return, or a fall into the next), each block's edges with their kind and target, the calls in it and their callees, and an indirect jump's table where it can be read. Calls that do not return must be known by name (`__stack_chk_fail`, `__syscall_do_cancel`, `abort`, `exit`), and instruction prefixes (`addr32 call`, `notrack jmp`, `bnd jmp`) read through, or a block runs on into the next and makes a false loop (it did in this round's first try at libc's `open`). Per stop: the visits to each block and the count of each edge so far (the renderer can count them from the `branch` events, if every taken branch and fall-through between blocks is there), and, for the folds, which blocks the whole recording ever reaches. For a descent in graph form, each frame's function's blocks. ## Token changes 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 | | --- | --- | --- | | `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.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 given-up rows fading before the kept glide, never both; the step 2.90 | | `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 | | `metric.graph` | none | a block's head 24; rows: offset ranged right at 72, line at 116, mnemonic at 128, operands at 212; 300 wide at least; fold past 16 rows to 4, `more`, 4; layers 48 apart, blocks 56, lanes 16 from 24; back edge down 14; port 40 in; arrivals 48 apart; right channel 32 out; corners 8; the exit's stub 14 and bar 28; a call's hook 14 out, a row down. Lens: boxes 24 high, 10 a row, 132 at least; layer gap 12; lanes 10 | | `time.leave` | none | chips 0.10 from 0.30; the edge 0.30; the mark 0.20 and 0.033 a 100 units, 0.50 at most; the count struck 0.10 after landing; the trail's cool 0.30; at a run 0.13 | | `time.spread` | none | rows 0.60 (`glide`, blocks 0.067 apart), then frames 0.20, then edges 0.20 each, 0.033 apart | | `time.ascend` | none | `close` 0.20 a row, 0.03 apart, from 0.80; the lane back 0.20; the caller's kept rows 0.30 (`glide`), then the given-back rows 0.20; the step 2.50 | | `metric.segments` | none | the whole 20 wide, the stage's height, its labels 12 left of it; a box 180 wide (108 in a column of 880), framed 2 out, 48 apart; bands 30% over the page, named from 6 tall, permissions inside from 28; the names 64 past the box, rows 24, a band's row indented 24, sizes ranged right 132 in, files at 252 on a bracket at 240; leaders 8 out, 20 short, 12 in; the magnification 2 `rule`; a dump's place: its link 3 in the stack's ink over y 56, standing at 60% toward the page | | `time.enlarge` | none | the line framed 0.10; the ride 1.20 (`glide`); page lines 0.20; names 0.20 each, 0.033 apart, a leader 0.10 before its address; the next cluster as one lands | | `time.regroup` | none | rows making room 0.30, down 0.20, left 0.30; veil 0.30; offsets 0.20 each, 0.033 apart; a byte's flight 0.60, 0.10 apart; the gaps 0.20; the zeros 0.20; at a run a word 0.133, rows 0.10 apart | | `metric.aligned` | `interleaved` only | `columns`: the seam 48 after the longest line in the window; each column's place ranged right 132 into it, its text 24 after; a line's first row `raised` | Unchanged and already there: the 1920 stage and its splits, the palette with the marks of the last round (`wash`, `struck` `b54f42`, the corner), `metric.slot` with its offset and role, `metric.bytes`, `metric.pin`, `metric.node`, `metric.calls` (full), `metric.tie` (54, 950, 962), `stroke.tie`, `time.strike` (with `corner`), `time.link`, `time.project`, `time.pin`, `time.continue_wave`, `time.relayout_fade`, `time.flight`, `time.caption`, `caption_lead`, `time.run`, `sprint`, `ramp`, the camera's scales. ## Building it 1. Atoms: `address` (unbroken, `lead`), `arrow`, `value`, `mark`, `pin`, `bracket`. The gallery starts here. 2. `chain`, then `reg` and `slot`: the registers and the stack at rest. 3. `insn` with its columns and annotations; `line`; `thread`. 4. `bytes` and `hexdump`; `nodes` in the band; quiet brackets. 5. `strike`, `cool`, `read`, `extend` at density; the `cascade`. 6. `link` and `pin`; `project`; `echo`. 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: ```sh canim --export - --size 3840x2160 --fps 60 --frames N | ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - \ -c:v libx264 -crf 14 -preset slow -pix_fmt yuv420p \ -g 600 -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv out.mp4 ``` 1440p and 1080p are the master downscaled, never rendered at their own size: `ffmpeg -i out.mp4 -vf scale=2560:1440:flags=lanczos …`. The map, filling the frame, is drawn at half its units: 20 pixels a row's text in the 4K master.