# 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 frame on the 4K stage, mid-step](mock/17-subject.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. ## 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` | | 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop; opens a `loupe` | | | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) | | | [`slot`](#slot) | a word of the stack and its chain | pins; `free` | | | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` | | | [`line`](#line) | a line of source | `current`, `trail`; wide numbers | | | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run; wide address | | | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` | | 3 panel | [`registers`](#registers) | all seventeen | | | | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | 8 or 6 slots | | | [`backtrace`](#backtrace) | the call chain as rows | in the `none` split; the view of `calls`; a lens's drawing | | | [`source`](#source) | a window on the file | 14, 8 or 10 lines | | | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows | | | [`lens`](#lenses) | a drawing of some state over the program's two columns, and in the third the pane it is a view of | `beside`, `subject` | | | [`hexdump`](#hexdump) | memory, a `bytes` row a line | typed or by `fields`; `more` rows; `seen`; `given`; `memory` | | | [`loupe`](#loupe) | the memory round a pointer's target, floating over the context | two at most, in depth | | | [`nodes`](#nodes) [`array`](#array) [`calls`](#calls) `heap` `syscalls` `pages` | the drawings a lens can hold | | | 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) | 3840 by 2160: the lens and four columns | split `none`, `beside`, `subject` | | | [`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 | | | | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | ## 0. Tokens ### Grid 3840 by 2160 units, at 60 frames a second: the 4K master is a pixel a unit, and 1440p and 1080p are its downscales. The context keeps its type size (mono 20, rows of 24) and so holds four times what a 1920 stage held: see [the frame](#5-the-frame). | Token | Value | | --- | --- | | context mono | 20: an advance of 12, rows of 24 | | panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides. The last panel of a column runs to the stage's foot, less than a row of padding under its rows | | between panels | 12 | | columns | four of 880, at x 112, 1024, 1936 and 2848; the gutters between them, 32 each, belong to the ties | | strokes | 2: rules, frames, chain arrows. 3: a projection, a lens's frames at 1920 scale. 4: a link, the thread, a loupe's stem | **What reads where.** Mono 20 is 20 pixels at 4K, 13 at 1440p, 10 at 1080p. The context's code and digits read on a monitor from 1440p up, full screen; at 1080p they are sharp on a still but not after a stream's compression, and count as texture. So at 1080p the layout, the marks, the ties, the lens's drawing and the caption carry the story, and anything the narration needs read in the context is in the caption or under the camera at x2, which shows a quarter of the stage at 1080p exactly as the 1920 stage drew it. The caption, the clock's count and a lens's drawing are drawn at twice the 1920 sizes for that reason. ### 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 | | 40 | 24 | the clock's count; a lens's labels and pins beside | | 50 | 30 | a lens's values beside; its labels and pins as subject | | 70 | 42 | code inside a caption | | 90 | 54 | a subject lens's values; a value in flight | | 120 | 72 | a title card | A lens's drawing is specified below at the 1920 sizes (`nodes` 124 by 72, values 45) and drawn twice that on the 4K stage; so are its strokes, lanes and flights. Sans: 18 notes and legends, 20 tags, 80 on 108 the caption, 88 and 232 a card. **Floor: mono 20, sans 18,** in 4K units: 10 and 9 pixels at 1080p. **Nothing the narration depends on is only at 20:** it is also in the caption at 70, or the camera goes to it. ## 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 | | `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 (24 on the 4K stage) | | `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). ## 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 | | | --- | --- | --- | | 10 | 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 | | 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); 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 | | 264 | operands | as the disassembler writes them, whole; a jump's or call's target is an `address` in code ink | | 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 | **Room.** The row holds 50 characters from 264, to 12 from the panel's edge. Operands are never cut where the row has room, and never inside `[]`: we do not hide what the instruction says. When the operands and the whole annotation do not fit, in this order: 1. the annotation moves left to where it just fits, never left of 564; 2. a size word (`qword ptr `) goes from a memory operand whose size a register operand gives: `mov rax, [rbp - 0x28]`. Nothing is lost; 3. the operands give way to the annotation: they end where it begins, in 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 | **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` | | writes memory | the same chain; the value after `holds` is `struck` | | only sets a register | a small `reg`: `rax 28b41090 ◂ 4` | | jumps on a condition | `taken` in primary, or `not taken` in dim; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37` | | calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there | | returns | `→ 10018b0 main+80` | | makes a system call | its name and arguments by name, as a call; the kernel's rows hang under it on vellum | Mocks 9 to 11 show the read, the register-setter, the taken jump and `outside`; 12 a call with its argument, a write, and operands longer than 24 characters with the annotation moved right of them. Return and syscall annotations are not drawn. ### 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. **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 | | | --- | --- | --- | | 7 | bracket | `quiet`, on a row that holds a drawn thing; `tie` when a projection ends here | | 18 | 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 eight digits leaves them at 132; the stack's twelve put them at 174, and the reading at 682 (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. 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. ## 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, low addresses on top, a column of its own the stage's height: 69 words, 552 bytes, in every split. `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** begins at rsp, and a small program's whole stack is in it: its frames, main's, libc's, and the process's start. Where the newest frame `[rsp, rbp+16)` is longer than the window, it scrolls down it by whole slots ([`scroll`](#6-verbs)) to keep the slot a step touches in its middle third, and stays there until a step touches a slot outside it; 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: `69 words from rsp`, or the range when scrolled (`rsp+20 to rsp+240`), and `· the frames they belong to`. ### backtrace `call` rows, newest on top: sixteen, under the registers, in every split; the view of a [`calls`](#calls) lens (32, and the panel under the registers is then `memory`); the drawing of a [`backtrace` lens](#lenses), as long as the drawing is high. More frames than rows: the oldest go, and the tag's note counts them, `newest on top · 2 more`. 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: 69 lines in `none`, 56 beside a lens, 43 as its subject; a file shorter than that is whole, the rows under its end empty. Tag: the file, and `lines 19 to 61 of 262899`, or `lines 1 to 42 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)). ### disasm `insn`s in address order, a column's height: 69 rows in `none`, 56 beside a lens, 43 as its subject. - The pc's row is in the window's middle third; the window is the function's and as much of its neighbours as fits, above and below. At this length a small function is whole, and its callers and callees around it are context, not noise: they are `outside`, plain, each under a rule and its name. - The window moves only when the pc leaves its middle third, by whole rows ([`scroll`](#6-verbs)), or fades through when the new pc is farther than the window's height. - 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. ### lenses A lens is **a drawing, over the program's two columns, and in the third column, beside it, 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. The drawing is 300 high beside the context and 604 as its subject, and drawn at twice the 1920 sizes given here; the view is 32 rows in both ([the frame](#5-the-frame)). | 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 | | `heap` | the heap to scale: chunks, bins | a `hexdump` of the chunk in hand | 4 at camera scale | | `calls` | a call tree under its caller, results on the shoulder | the `backtrace`; each node is also a `call` span on the stack, tied by `project`. Subject only: a tree needs the height | 12; 1 at camera scale | | `backtrace` | the call chain itself, as `call` rows (eleven as subject): how the program came to be here, when that is the story and no one function's calls are | a `hexdump` by `fields` of what the newest call was handed (the struct an argument points at, a buffer), at its stop | 13, 14 | | `syscalls` | the kernel's side, on vellum: the calls so far, the call decoded, the bytes it holds | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 3 at camera scale | | `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`, in the `none` split, is the third panel of the third column (32 rows): a `hexdump` of the region the step touches, kept round what it reads or writes, typed where the recording types it; with a lens, the lens's view is this. 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 880 by 132 (`beside`) and by 284 (`subject`) at the 1920 sizes, to be drawn twice that over the program's columns. 2. Its view, a pane of 32 rows that fits a column, 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. ### hexdump `bytes` rows, sixteen a row, a window of the region kept round the rows the step touches: 32, 512 bytes, as a lens's view and as `memory`; nine in a [`loupe`](#loupe). 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`, 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 (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 row in the backtrace, the view, 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 kernel's side, on vellum (solid vellum is the kernel): the calls so far, newest on top, each with what it returned; the call in hand, decoded: its name, its arguments by name beside the registers the call takes them in (`rdi fd 3 "t.db"`), `returns`; and the bytes it was given or filled, ten a row, two rows. Its view is a [`hexdump`](#hexdump) by `fields` of the buffer, `given`. A **crossing** is a step that makes one system call; its timetable is [motion.md's](motion.md#a-system-call). What it may claim: - A register is framed as carrying an argument only while it holds that argument at the stop shown. Stopped in the caller of libc's wrapper, `pwrite64`'s buffer and count are in rsi and rdx, but its descriptor is not yet in rdi nor its offset in r10: those two are not framed, though the kernel's rows name them. - Nothing on the kernel's side changes before the arrow down arrives. `returns` takes the value before the arrow back leaves, rax is struck as it lands, and everything else the step changed (the registers the wrapper and the call clobbered, pins, links, a result stored in memory) waits for rax. - A step that makes several calls (a continue through a library) is not a crossing: the list takes them, oldest first, 2 f apart, each fading in; the newest is decoded; no arrow, no bytes. ### 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 nine `bytes` rows: the target's row in the middle, four before and four after (144 bytes), its runs typed (a node's value and next, malloc's words) or by `fields` | | 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` (4 units, the target's region ink, head 12 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.** Beside what it opens from, its tag level with the pointer's row: from the registers over the stack's column, from the stack over the registers', from the disassembly or a dump over the column on its right; a loupe opened from a loupe 120 to the right and just under the pointer it opens from, over the older loupe'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; where the first place would, it takes the other side, then the place under its pointer; and it stays inside the stage. **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)). Mock 18. ## 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, 4 units: a `tie` bracket on the line at the source's right edge, one on each run at the disassembly's left, and between them a line down the gutter (x 1008), the two side by side | | `link` | this register now points at that | the `reg` just struck; the row or node whose address it holds | for the step that set it | 3 units, in the ink of the region pointed into, head on the target; ends in the target's `pin` and leaves it behind | | `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; or the backtrace row of a frame made or ended (a `calls` lens's view); 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). On the 4K stage the four columns leave three gutters: | Channel | Carries | | --- | --- | | the gutter between source and disassembly, x 1008 | the thread | | the gutter between the program and the third column, left lane x 1912 | a link from a register up to the pin under a node: it leaves the register's row at its left, climbs, and turns into the drawing's bottom lane | | the same gutter, right lane x 1924 | a projection from the view to the drawing: it leaves the view's row at its left and climbs to the drawing's top lane, or for a call's node goes down to its bottom lane | | the gutter between the third column and the stack, x 2832 | a link from a register to a slot: it leaves the register's row at its right edge and enters the slot's pin lane | | 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 | | 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 into the drawing keep to the gutter beside it, links in the left lane arriving from below, projections in the right lane; links to the stack keep to the gutter beside the stack: so the ties of one step cannot cross. A calls lens's projection leaves the frame's row in the backtrace, its view (the frame the return address made), not the stack's slot, which is two columns away. 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. **Order.** A tie arrives before the thing it points to reacts: see [`link` and `project`](#6-verbs). Mocks 16 to 18 show the ties on the 4K stage: the thread across its gutter, a link and a projection, two stems. ## 5. The frame The stage is 3840 by 2160 units, the 4K master's pixels. | Band | y | | | --- | --- | --- | | margin | 0 to 96 | page | | stage | 96 to 1784 | 1688, a panel of 69 rows: the lens and four columns | | clock | 1796 to 1804 | | | caption | 1824 to 2064 | | | margin | 2064 to 2160 | page | No data below 1784: a player's controls cover it. Sides: 112. **Four columns of 880**, at x 112, 1024, 1936 and 2848, 32 apart. **A**, the source, and **B**, the disassembly, side by side: what was written, what runs, the thread between them in their gutter. **C**: the registers, the backtrace, and `memory` (or a lens's view). **D**: the stack, the stage's height. **The lens**: its drawing over A and B, its view in C. The split is the one thing about the layout a scene chooses, and it changes only how high the drawing is. | Split | Drawing (A and B) | Source (A) | Disassembly (B) | C | Stack (D) | | --- | --- | --- | --- | --- | --- | | `none` | | 69 lines, 96 to 1784 | 69 rows | registers 96 to 536; backtrace 16, 548 to 964; `memory` 32, 976 to 1784 | 69 slots, 96 to 1784 | | `beside` | 1792 by 300, 96 to 396 | 56 lines, 408 to 1784 | 56 rows | the view 32, 96 to 896; registers 908 to 1348; backtrace 16, 1360 to 1784 | 69 slots | | `subject` | 1792 by 604, 96 to 700 | 43 lines, 712 to 1784 | 43 rows | as `beside` | 69 slots | Against the 1920 stage: source 14, 8, 10 lines became 69, 56, 43; instructions 17, 17, 9 became 69, 56, 43; the stack's 8, 8, 6 slots 69; a dump's 5 or 7 rows 32. **What it costs**: the context's text is 10 pixels at 1080p, where it is texture (see [the grid](#grid)); the camera at x2 is how a 1080p viewer reads it, and the caption, the clock and the lens's drawing are twice their 1920 sizes so that they read anywhere. A file of more than 69 lines, and with a lens open any file, is still a window: the trade with rule 6 stands, at four times the window. | Of the frame | `none` | `beside` | `subject` | | --- | --- | --- | --- | | context | 72% | 56% | 50% | | lens (the drawing and its view) | | 15% | 22% | | caption band | 10% | 10% | 10% | ### clock and caption - **`clock`**: a 4-unit rule the width of the stage at y 1798; gold, 8 high, along it as far as the recording has run; `moment 72 of 95` in mono 40, faint, under its right end. 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 80 on 108, ranged left on the margin; code in it is mono 70. 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 | | changes | only in a rest, never under a moving thing | | 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 (2560 by 1440: three columns' upper half, or the lens), x2 (1920 by 1080: two columns, 45 rows, at 1080p exactly the 1920 stage's density), x4 (960 by 540: one column's 20 rows). It is for reading, and always comes back: on the 4K stage it is also how a small screen reads the context. ## 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 | 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 after the one it opened in, unless the narration holds it; 120 f at most without a change | | `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 | `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 | 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; values change with an ember, never a solid; no ties but the thread. 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 | | `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 | | `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. 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) | 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. ## Composition **What may contain what.** - The stage holds the lens and four columns; the lens is two panels, its drawing over the first two columns and its view in the third. A column holds panels. A panel holds a tag and rows, or (a lens) a tag and a drawing. A row holds atoms. Nothing nests deeper. - 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 9 to 14, one function a block under the block's name; `mock/dense.py` places those blocks on the 4K stage and draws 15 to 18; `mock/gen.py` draws 1 to 8. Look at 15 to 18 at full size: they are the 4K master's pixels. 9 to 14 were drawn on the 1920 stage, before the 4K one: their blocks and marks are the catalogue's, their layout is not (two columns; the calls tie from the stack), and the camera at x2 is the nearest thing to them now. ```sh cd design/mock python3 -B context.py && for n in 09-context 10-context-step 11-context-lens 12-calls-subject \ 13-sqlite-row 14-sqlite-page; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done python3 -B dense.py && for n in 15-marks 16-none 17-subject 18-loupes; do resvg $n.svg $n.png; done 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: moment 71 of `targets/list`, stopped at `mov rdi, [rdi + 8]` | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot`, `pin` row; `call` spans; `insn` current, ran, ahead, outside, with the jump lane; `line`; `bytes` with number, pointer, loose (the allocator's), unread and `pad`; `nodes` with pins under, two names on one; `thread`; marks current, held, trail | | [10](mock/10-context-step.png) | the same, mid-step | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin, rax's name kept on its side; `projection` | | [11](mock/11-context-lens.png) | `subject` | the drawing 296 high and a size up, its view a dump of seven, nine instructions, six slots | | [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments; `call` spans with arguments; the stack's window from rsp, six slots; a `projection` from the return address to the new node; `insn` with a call and its argument, a write, and operands of 27 characters whole | | [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in | | [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the kernel's side in the band; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed | | [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 | | [16](mock/16-none.png) | `none` on the 4K stage, at rest: `targets/list` stopped at the load in `reverse` (a fresh recording, `mock/list-dbg.txt`) | four columns: 69 lines of source (the file whole), 69 instructions (`reverse` and its neighbours `outside`, under rules and names), the registers, the backtrace, `memory` of the heap by its words, the stack's 69 slots with offsets, roles and the spans of five frames down to the process's start; the thread across its gutter | | [17](mock/17-subject.png) | `subject` on the 4K stage, mid-step: the load done | the list drawn twice the size over A and B; its view of 32 rows with the fieldless rows folded into `more`; 43 lines and 43 instructions; a link from rdi to its pin and a projection from the view; struck, held and current as B | | [18](mock/18-loupes.png) | `none` on the 4K stage, mid-step, two loupes open | a `loupe` from rdi floating over the stack's column, its node framed; a second from that node's `next`, deeper, over the first's lower rows; their stems; the read in `memory` by `echo` | | [1](mock/01-fib-recursion.png) | first pass | `calls` at camera scale | | [2](mock/02-list-insert.png) | first pass | `nodes` at camera scale; `allocated` | | [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` | | [4](mock/04-malloc-glibc-musl.png) | first pass | `heap`; `freed` | | [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 system call, `not taken`, a jump out of the window; operands giving way (none in 9 to 14 needs to). - `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`, `heap`, `pages` in the band. - A loupe opened from the stack, the disassembly or a dump; a loupe typed by `fields`; a third closing the first. - 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 14** 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`). The frames' extents are read off the frame-pointer chain. 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 (`theme.zig` as of 21:15); the tokens are under [Token changes](#token-changes). Last round's `continue` and crossing stand as specified. 1. **The 4K stage.** The design unit becomes the 4K master's pixel: `canvas` 3840 by 2160, the stage 3616 by 1688 at (112, 96), the clock at 1798, the caption band 1824 to 2064. Export at 3840 by 2160 natively (`ui.scale` maps 1920 units to the scene now); 1440p and 1080p are downscales of it (lanczos), never renders of their own. 2. **Four columns** (`layout`): source, disassembly, a third column (registers, backtrace, `memory` or a lens's view), the stack; the splits as [the frame's table](#5-the-frame): `Split` gains `memory`, the view moves into the third column, the stack runs the stage's height (69), `dump_rows` 32. The test "the splits fill the stage" changes with it; a column's last panel runs to the stage's foot. 3. **The thread across a gutter**: the source and the disassembly are side by side; the thread's brackets at the source's right edge and the disassembly's left, its line down x 1008. 4. **Ties in three gutters** ([Routes](#4-ties)): links into the drawing at 1912, projections from the view at 1924, links to the stack at 2832; a calls lens's projection leaves the backtrace row (its view), not the stack's slot. 5. **A lens's drawing twice the size**: nodes, cells, the calls tree, the kernel's side, their labels, strokes, lanes and flights at twice the 1920 numbers (`drawing_scale` 2), over the program's two columns. 6. **The slot's columns** ([`slot`](#slot)): pins 10 to 112, the offset from rsp ranged right to 172, the address from 184, the role ranged right where the chain's room ends; spans for every frame in view. 7. **The disassembly's window**: 69, 56 or 43 rows with the pc in its middle third and the neighbouring functions `outside`, plain, under a rule and their name; fade through beyond the window's height. 8. **`memory`** in `none`, and every dump 32 rows, its rows that hold no field always folded into `more` (now only when the region is longer than the window). 9. **Marks** ([`mark`](#mark)): `current` a white wash across the row (`212644`) and the gold plaque; `struck` on `b54f42` with bright bold digits (the arm, a projection and the corner stay full vermilion); `held` a turned corner, a vermilion right triangle 9 on its sides at the value's top left (12, at the drawing's scale, on a cell). The tick and the bar go. 10. **`loupe`** ([`loupe`](#loupe)): the block, its placement and its stems; `open` and `close` ([verbs](#6-verbs)); at most two; the one elevation in the frame (`lift`, `shade`). 11. **Still from the last round**: the calls tree's small size and folds, a frame name's 300 units, `time.caption_max` and `time.first_step`. **What the recordings must hold** for these, which they do not now: - **Code round the pc**: 69 instructions with the pc in the middle third means about 300 bytes of code before the pc and 300 after; simplest is the program's text, symbols and line table once per recording, and for a library 512 bytes either side of each pc in it, with its symbols. - **The stack**: 69 words from rsp, 552 bytes, at every stop; with the window's scroll down a long frame and `free` slots under the camera, from rsp − 128 to rsp + 1024 (or the stack's top). The sqlite scene records 512, `ztrace record`'s default is 128. - **Round a loupe's target**: 80 bytes before and 80 after every chased target the recording does not already watch (the recorded stack, the tracked heap), clipped to its mapping: 160 where 32 are recorded today. - **For the slot's roles**: the call frame information at each frame's pc (which registers its prologue saved, where); the debug info's locals at each frame's pc (name, and where: a frame offset or a location list); the process's first stack pointer (argc, argv, envp, auxv sit at it). Saved rbp and return addresses come from the frame chain, which the recording has. - **`memory`**: the 512 bytes round what a step reads or writes; the heap is watched already, unwatched memory needs the 160 above at least. ## Token changes Against `anim/src/theme.zig` as it is now (21:15): "In theme.zig" is what is in the file, "Is" what the documents say. | Token | In theme.zig | Is | | --- | --- | --- | | `canvas.width`, `height` | 1920, 1080 | 3840, 2160 | | `canvas.margin_x`, `margin_y` | 64, 48 | 112, 96 | | `canvas.columns`, `column`, `gutter` | 12 of 120, gutters 32 | 4 of 880, gutters 32 | | `canvas.stage` | 64, 48, 1792 by 840 | 112, 96, 3616 by 1688 | | `canvas.clock_y` | 900 | 1798 (the rule 4, the gold 8) | | `canvas.caption`, `caption_baseline`, `caption_max_width` | 64, 912, 1792 by 120; 990, 964, 1018; 1400 | 112, 1824, 3616 by 240; 1980, 1928, 2036; 2800 | | `layout.program`, `state` | two columns of 880 | four: `source` 112, `disasm` 1024, `third` 1936, `stack` 2848 | | `layout.Split` | band, view, source, disasm, registers, stack, backtrace, `dump_rows` | the same and `memory`; the view in the third column; `dump_rows` 32 | | `layout.split.none` | source 14, disasm 17; registers, stack 8, backtrace 4 | source 69, disasm 69; registers, backtrace 16, `memory` 32; stack 69 | | `layout.split.beside` | drawing 152 by 880, view 152 (5); source 8, disasm 17; registers at 212, stack 8 | drawing 300 by 1792; view 32 at 96; source 56, disasm 56; registers at 908, backtrace 16; stack 69 | | `layout.split.subject` | drawing 296, view 200 (7); source 10, disasm 9; registers at 260, stack 6 | drawing 604 by 1792; view 32; source 43, disasm 43; registers at 908, backtrace 16; stack 69 | | `size.sans.caption`, `caption_leading` | 40, 54 | 80, 108 | | `size.mono.value` (code in a caption) | 35 | 70 | | a lens's drawing | `metric.node`, `calls`, the array's cells at their sizes | the same numbers, drawn at `drawing_scale` 2 | | the clock's count | mono 20 | mono 40 | | `stroke.tie` | thread 3, link 3, projection 2 | 4, 4, 3 | | `metric.tie` | `thread_x` 54, lanes 950 and 962 | `thread_x` 1008; lanes 1912 (link), 1924 (projection), 2832 (to the stack) | | `metric.slot` | lane 10 to 112, chain 122, room 136 | lane 10 to 112, `offset` ranged right to 172, `address` 184, the role ranged right at the room's end | | `mark(.current)` | ember `4a3d1c` across the row | `color.wash` `212644` across the row; the plaque stays gold | | `mark(.write)`, a strike's paper | `ff6a4a`, digits in ink | `b54f42`, digits bright; `ff6a4a` stays for the arm, a projection and the corner | | `held` | a tick 4 wide (`metric.context.tick`); a bar 4 high (`metric.ember_bar`) | a turned corner, 9; on a cell 12 | | `color.lift`, `lift_tag`, `shade` | none | `121c52`, `22317a`, `02061a` | | `metric.loupe` | none | 880 wide, 9 rows; shadow 12 right and 16 down, 20 and 26 for a deeper one; a deeper one 120 to the right; stem 4, head 12 | | `time.loupe` | none | `read` 0.10; `stem` 0.30 (0.50 over 600 units); `rise` 0.20, shadow 0.30; `frame` after 0.10; `close` 0.20 | | `camera.scales` | 1, 1.5, 2, 4 | the same; at x2 the frame is 1920 by 1080 of the 4K stage | | from the last round | | `metric.calls` small (36, 38, badge 24) and folds; `metric.span.name_max` 300; `time.caption_max` 12.00; `time.first_step` 4.00 | Unchanged and already there: the palette but for the marks above, region inks, the context's type sizes (mono 20, rows 24, tags 24, padding 4), `metric.bytes`, `metric.pin`, `metric.node` and `metric.calls` (drawn twice), `color.veil_alpha`, `time.veil`, `time.strike`, `time.link`, `time.project`, `time.pin`, `time.continue_wave`, `time.relayout_fade`, `time.flight`, `time.caption`, `caption_lead`, `time.run`, `sprint`, `ramp`. ## 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. Export: ```sh canim --export - --size 3840x2160 --fps 60 --frames N | # the 4K stage's own pixels 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 …`.