diff options
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 1224 |
1 files changed, 692 insertions, 532 deletions
diff --git a/design/README.md b/design/README.md index b108cf2..8624017 100644 --- a/design/README.md +++ b/design/README.md @@ -1,651 +1,811 @@ -# canim: the look +# canim: the design language -How a canim frame is laid out, coloured and set. How it moves is in -[`motion.md`](motion.md). The numbers are tokens in `anim/src/theme.zig`; -the changes this revision asks of them are [listed below](#token-changes). -Eleven frames drawn with these rules are in [`mock/`](mock). +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. -**Revision 2.** The first pass put one idea on screen in a few sparse -panels. The premise now is a debugger's: *show the whole context, always*, -as pwndbg does, and put the scene's idea beside it as a lens on the same -state. Sections marked **(rev 2)** are new or changed; what was withdrawn is -in the table that follows. +- 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 idea, in six rules: + -1. **Lapis page, vellum ink.** 0x4200.cafe's own palette: 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.** **(rev 2)** - The colour of a value's digits is where it points (stack, heap, code, - data), a keyword, a string. A fill, a frame, a tick or a plaque behind or - beside it is an event: written, read, current. The two never share a - channel. +## 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 tick beside it 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 and dashed, unknown is two dots. -4. **Solid vellum is the kernel**, at every scale, and nothing else. -5. **Panels are acme windows.** A tag with a square box, a 2-unit rule, a - body. Square corners, no shadows, no gradients, no glow. -6. **The whole context, always, and the lens beside it.** **(rev 2)** Every - register followed as far as it points, the instructions at the pc, the - stack, the backtrace and the source are in the same place in every frame. - A list, a tree, an array is a lens on that state: never shown instead of - it, and visibly tied to the words it is made of. The machine is set in - JetBrains Mono; the narrator in Go. + 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, seventeen 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 -## What changed +Six layers. A block is made only of blocks from the layers above it in +this table. -| | First pass | Revision 2 | -| --- | --- | --- | -| On screen | one to four panels chosen by the scene | the whole context in every frame, and one lens | -| Layouts | `solo`, `duo`, `trio`, `quad`, `trio_hero`, `far`, `crossing` | one frame with three splits; only title cards are anything else | -| Running head, level rail | a band at the top | gone: the rows went to the stage; the frame itself is the rail | -| Mono | Go Mono, 30 for anything read | JetBrains Mono NL, 20 in the context | -| Hard floor | mono 30, sans 28 | mono 20, sans 18; see [what a phone loses](#type) | -| Hue on digits | syntax only | region: where an address points | -| `pointer` role (orchid) | a frame and an arrow for every pointer | gone: a pointer is inked by its region; orchid is now `data` | -| Arrows to targets | always drawn | drawn in a lens, and for the one pointer a step follows | -| Changed a moment ago | ember fill and a bar | in the context, a tick at the value's left; ember and bar in a lens's cells | -| Registers | eight by default | all sixteen, rip, flags, each with its telescope | -| Stack | cards, or a byte grid | a telescope of eight words, and the backtrace under it | -| Source | the lines that fit a panel | the whole file, scrolling to keep the line in view | -| Levels | different layouts, a camera between them | places in one picture; the camera is for reading | -| Camera scales | 1, 2, 4 | 1, 1.5, 2, 4 | +| 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`, `allocator`, `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 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 | +| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) | +| | [`slot`](#slot) | a word of the stack and its chain | pins | +| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` | +| | [`line`](#line) | a line of source | `current`, `trail` | +| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run | +| | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` | +| 3 panel | [`registers`](#registers) | all seventeen | | +| | [`stack`](#stack) | the words from rsp, and the frames they belong to | 8 or 4 slots | +| | [`backtrace`](#backtrace) | the call chain as rows | only in the `none` split | +| | [`source`](#source) | a window on the file | 14, 8 or 10 lines | +| | [`disasm`](#disasm) | the instructions round the pc | 17 or 11 rows | +| | [`lens`](#lenses) | a drawing of some state, and the bytes it is drawn from | `beside`, `subject` | +| | [`hexdump`](#hexdump) | memory, a `bytes` row a line | | +| | [`nodes`](#nodes) `array` `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` | +| | [`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 band and the two 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 | | +| | [`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 | | +| | [`cascade` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | -## The frame (rev 2) +## 0. Tokens -1920 by 1080 logical units; a 4K master is two pixels a unit. Master at -2160p60: at this density the extra resolution is not a nicety. +### Grid -| Band | y | What | -| --- | --- | --- | -| margin | 0 to 48 | page | -| stage | 48 to 888 | the context and the lens: 35 rows of 24 | -| clock | 898 to 902 | a rule the width of the stage; gold along it as far as the recording has run; `moment 72 of 95` under its right end | -| caption | 912 to 1032 | one or two lines of narration | -| margin | 1032 to 1080 | page | +1920 by 1080 units; a 4K master is two pixels a unit, at 60 frames a second. -Side margins are 64. Two columns of 880 with 32 between them; panels in a -column are 12 apart. A panel is a tag of 24, 6 of padding, rows of 24, 6 of -padding: 36 + 24 a row. +| 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 | +| between panels | 12 | +| columns | two of 880, at x 64 and 976; the gutter between them, 944 to 976, belongs to the ties | +| strokes | 2: rules, frames, chain arrows, a projection. 3: a link, the thread, a lens's frames. 4: a tick | -**The state column** (right, x 976 to 1856) is the same in every frame of -every scene: +### Colour -| Panel | Rows | Height | y | +| | Hex | On page | Use | | --- | --- | --- | --- | -| registers | 18: sixteen, rip, flags | 468 | 48 to 516 | -| stack | 8 words from rsp | 228 | 528 to 756 | -| backtrace | 3 frames, then a count | 108 | 768 to 876 | +| 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, an allocator's bytes, notes | +| faint | `6a7ab8` | 4.5 | chain arrows, line numbers, a decimal beside its hex | +| ink | `050a24` | | letters on a solid mark | -**The program column** (left, x 64 to 944) holds the lens, the source and -the disassembly, top to bottom: the idea, its text, its instructions. It has -three splits, and the split is the only thing about the layout a scene -chooses: +**Regions: the ink of an address**, as pwndbg colours them. The legend is +the registers' tag, always on screen. -| Split | Lens | Source | Disassembly | When | -| --- | --- | --- | --- | --- | -| no lens | | 21 lines, 540 | 10 rows, 276 | the machine alone | -| lens beside | 312 | 12 lines, 324 | 6 rows, 180 | the default: the machine is the subject ([mock 9](mock/09-context.png)) | -| lens as subject | 432 | 8 lines, 228 | 5 rows, 156 | the idea is the subject ([mock 11](mock/11-context-lens.png)) | +| 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 | -As the subject the lens is also a size up: mono 25 on rows of 30, values at -35. Moving between the last two is a layout change (0.8 s): the source gives -up four lines and the disassembly one row. +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. -Of the frame's area: +**Marks: the colour of an event.** Solid, and the ember it cools to. -| | No lens | Lens beside | Lens as subject | -| --- | --- | --- | --- | -| state column | 35% | 35% | 35% | -| source and disassembly | 35% | 21% | 16% | -| **context in all** | **70%** | **57%** | **51%** | -| **lens** | | **13%** | **18%** | -| caption band | 10% | 10% | 10% | +| Role | Solid | Ember | +| --- | --- | --- | +| current | gold `e8c46a` | `4a3d1c`; trail `ae9350`, `746235`, `463b20` | +| write | vermilion `ff6a4a` | `5a2218` | +| read | `6fd6e6` | `1c4652` | +| allocated | `7fdc9a` | `1f4a33` | +| kernel | vellum `eee6d2` | | -The lens never has more than a fifth of the frame, and that is the cost of -the premise. When an idea needs to be large it gets the camera (below), for -a few seconds, and the frame comes back. +**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. -**Place is meaning.** Down the program column abstraction falls: idea, C, -instructions. The state column is what they act on. The lens is top left, -where the eye starts, and next to the registers that point into it. The -kernel is still vellum and still underneath: its rows hang under the -`syscall` instruction in the disassembly, and a crossing is a lens. +### Type -**No data below y = 888.** The player's controls and subtitles cover the -caption band. +| 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 | -## Colour +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/`. -| | Hex | On page | On `raised` | Use | -| --- | --- | --- | --- | --- | -| page | `0a1030` | | | the ground; panel bodies too | -| raised | `16245f` | 1.3 | | tags, cells, plaques, node bodies | -| rule | `3a4a8a` | 2.2 | 1.7 | rules, hollow cells, wedges; fill of bookkeeping | -| text, bright | `fff8e8` | 17.6 | 13.7 | titles, a value in flight, a landing frame | -| text, primary | `eee6d2` | 14.9 | 11.6 | numbers that are not addresses, names of code, plain code | -| text, dim | `9aa6d9` | 7.8 | 6.1 | register names, notes | -| text, faint | `6a7ab8` | 4.5 | 3.5 | arrows in a chain, offsets, line numbers, a decimal beside its hex | -| ink | `050a24` | | | letters on a solid accent | +| Mono | Advance | For | +| --- | --- | --- | +| **20** | 12 | the context, the dump, a lens beside | +| 25 | 15 | a lens's values; 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 | -### Regions: the ink of an address (rev 2) +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. -As pwndbg colours them, and as its users read them without thinking: +## 1. Atoms -| Points into | Ink | On page | Also | -| --- | --- | --- | --- | -| stack | yellow `f2d675` | 13.0 | | -| heap | blue `86b6ff` | 9.0 | | -| code | red `ff8f9a` | 8.5 | always followed by its name | -| data, writable | purple `d59cf5` | 8.8 | | -| writable and executable | its region's ink | | a 2-unit underline | -| read-only data | primary `eee6d2` | 14.9 | plain, as pwndbg leaves it | -| nothing: not a pointer | primary | | see [what a value shows as](#what-a-value-shows-as-rev-2) | -| a string | `b5e8c8` | 13.6 | in quotes | +### address -The legend is always on screen, as pwndbg's is: the six words, each in its -ink, in the registers' tag. +Lower-case hex, **unbroken**, as long as it is, no `0x`, no leading zeros: +`28b41090`, `7ffe970f17b0`, `1001926`. Its ink is its region. -These are tints, lighter and less saturated than the marks, so a frame of -them is quiet. Every one reads at 4.6 or better on every ground it can sit -on, the embers included. +| 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: `libc+27781` | +| `rwx` | a 2-unit underline | -### Marks: what happened +States: plain; `struck` (bold, in ink, on solid vermilion 5 wider each +side); `read` (a 2-unit frame, 6 out); `held` (a tick at its left). Data: +a word and the mapping it lies in. Mocks 9 to 11, everywhere. -| Role | Solid | Ember | In the context (mono 20) | In a lens's cell | -| --- | --- | --- | --- | --- | -| current | gold `e8c46a` | `4a3d1c` | solid plaque on the label, ember across the row | the same | -| write | vermilion `ff6a4a` | `5a2218` | solid behind the value, digits bold in ink | solid fill, pulse | -| changed (held) | vermilion | | a tick, 4 wide, at the value's left, for three steps | ember and a 6-unit bar | -| read | `6fd6e6` | `1c4652` | a 2-unit frame, no fill | a 3-unit frame, ember inside | -| allocated | `7fdc9a` | `1f4a33` | | ember block in a solid frame | -| freed | no colour | | | hollow, dashed, hatched | -| fault | vermilion | | hazard bands round an ink plaque naming it | the same | -| attention, landing | bright | | a 2-unit bright frame | a 3-unit bright frame; a veil on the rest | -| link, flow | the target's region ink; primary | | a 3-unit arrow, for one step | a 3-unit arrow | -| unknown | faint | | two 6-unit squares | the same | -| kernel | vellum `eee6d2` | | the ground | the ground | +### value -**How the two never fight.** +What is not an address. The tracer classifies; the class decides. -- A region is letters; a mark is never letters. During a strike the digits - are bold ink on solid vermilion: for 0.6 s "written now" is all that value - says. As the fill goes the digits come back in their region's ink. -- A held change does not sit under the digits it marks. It is a tick in the - gap to their left, the `*` pwndbg puts before a changed register. The - underline is left free to mean writable-and-executable. -- A read is a frame, outside the digits, and brings no fill. -- The current row is the one place region ink sits on a coloured ground: - code red on the gold ember, at 4.9. -- In a lens's cells (mono 25 and up, a box of their own) the ember stays: - there is room for it and the digits on it are measured (4.6 to 8.7). +| 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 | +| boolean, character | the debug info types it so | `true`; `0x41 'A'` | +| unknown | never observed | two dots | -**The `pointer` role is gone.** Being a pointer is not a colour any more: -every address is inked by where it points. Its orchid is `data`. Its forms -survive as the *link*: an arrow, and a frame round the bytes that make one -pointer, in the ink of the region pointed into, drawn in two places only: -inside a lens (a list's arrows), and for the single pointer a step follows -or rewrites. +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. -**Pigments** still say *which object*, across views: ochre `8a5e0c`, teal -`17707c`, madder `a03060`, malachite `1c7450`, violet `6a3fb0`, azurite -`2f5fc4`; at most four, each with its name. In the context they are a -lens's way of naming an object and its rows, and never a ground under -region ink. +### arrow -**Code** (pardes's four classes): plain `eee6d2`; keyword `c0dcff`, bold; -string and number `b5e8c8` (was `c8f0d8`: too close to plain at 20); -comment `9aa6d9`, italic. In the disassembly a mnemonic is a keyword. +30 wide: a 2-unit shaft and a head 8 by 10, faint. -**Colour vision.** Blue ground against gold and vermilion is the axis every -common deficiency keeps. Region ink *is* hue alone, as it is in pwndbg, and -heap, data and code have the same luminance; a deuteranope cannot tell heap -from data by colour. What is left for them: code always has its name after -it, a string its quotes, stack is far lighter than the rest, and an -address's own top digits say where it is. That is weaker than everything -else here and it is the price of the convention. +| 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 | | -**After 4:2:0.** Mock 10 through x264: at 1080p (CRF 30) and at 720p -(CRF 28) every chain reads and every region keeps its colour. At 480p the -digits can no longer be trusted (`0` and `8` fall together); ticks, the -strike, the region colours, the gold rows and the caption survive. +A **hop** is a `points` arrow and the address after it: the unit a chain +is counted, cut and re-followed in. -## Type +### byte -**(rev 2)** One mono family for code, registers, hex and memory, so the -whole context sits on one grid; Go stays for everything said about it. +Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth. -| Face | File | For | +| Kind | Ink | Paper | | --- | --- | --- | -| JetBrains Mono NL Medium | `JetBrainsMonoNL-Medium.ttf` | everything mono at 20 and 25 | -| JetBrains Mono NL Regular | `JetBrainsMonoNL-Regular.ttf` | mono at 30 and larger | -| JetBrains Mono NL Bold | `JetBrainsMonoNL-Bold.ttf` | keywords, mnemonics, a struck value, plaque letters | -| JetBrains Mono NL Italic | `JetBrainsMonoNL-Italic.ttf` | comments | -| Go | `Go-Regular.ttf` | captions, notes | -| Go Medium | `Go-Medium.ttf` | tags, labels | -| Go Bold | `Go-Bold.ttf` | titles | +| `number`: a field that is not a pointer | primary | raised, one rect a field | +| `pointer`: a field that is one | the region it points into | raised, one rect a field | +| `allocator`: between allocations | dim | none | +| `unread`: never observed | two 4-unit squares, faint | none | -JetBrains Mono: OFL 1.1, `/usr/share/fonts/TTF/` (`ttf-jetbrains-mono` -2.304). Go: BSD-3-Clause, `/usr/share/fonts/go/`. +`pad`: in a little-endian word, 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. Marks are per run of +bytes, never per byte: see [`bytes`](#bytes). Mocks 9 to 11. -- **NL, not the plain family.** The plain one has ligatures: `->`, `!=` and - `>=` become single signs that are not in the source. NL is the same - design without them. (If the renderer can turn `calt` off, either will do.) -- **Medium at 20 and 25.** Light letters on a dark ground lose their thin - strokes first in a stream; at 720p Medium keeps its weight and Regular - does not. -- **Why not Go Mono too**: one family means a hex digit, a keyword and a - register name are the same width and weight, and the user asked for - JetBrains Mono where code is. Why Go stays: captions are the layer a - phone still reads, Go was the most legible of eight faces at 480 wide, - and the change of voice between machine and narrator is worth a second - family. +### mark -Its advance is 0.6 em, as Go Mono's was, so the rule holds: **mono sizes are -multiples of 5** and a character is a whole number of units, at 1080p and -at 4K. +What happened, on paper and never in the letters. -| Mono | Advance | Rows of | For | -| --- | --- | --- | --- | -| **20** | 12 | 24 | the context: every panel of it | -| 25 | 15 | 30 | a lens that is the subject; a lens's values | -| 30 | 18 | 36 or 48 | what the camera at x1.5 makes of the context | -| 35 | 21 | | values in a lens that is the subject; code inside a caption | -| 45 | 27 | | a value in flight | -| 60 | 36 | | a title card's numbers | +| State | In the context (mono 20) | In a lens's cell | +| --- | --- | --- | +| `current` | a gold plaque on the label, gold ember across the row | the same | +| `armed` | a 2-unit vermilion frame, the old value still in it | 3 units | +| `struck` | solid vermilion behind the value; digits bold, in ink | solid fill | +| `held` | a vermilion tick, 4 wide, the row less 6 tall, at the value's left, for three steps | a vermilion bar, 4 high, along the cell's bottom edge | +| `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 | -| Sans | For | -| --- | --- | -| 18 | notes in a tag, a note at the end of a row | -| 20 | a panel's title | -| 24 | a note beside a lens | -| 40 on 54 | the caption | -| 44, 116 on 128 | a title card | +One gold mark a panel. One step's writes in vermilion at a time. Mocks 9 +and 10 show current, struck, held, read, trail, unknown; 1 to 8 the rest. + +### plaque -**The hard floor is mono 20 and sans 18.** Nothing is smaller, anywhere. +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). -**What a phone loses.** Said plainly: at mono 20 the context is a picture -for a desk. On a phone held sideways an x-height is 0.8 mm, and at 480p no -hex digit can be trusted. A phone viewer keeps the caption (40), the -layout, the gold rows, the strike and its link, the region colours as -colour, a lens that is the subject, and whatever the camera brings to 30. -So one rule protects them: **nothing the narration depends on is only at -20.** The value it names is also in the caption, in mono 35, or the camera -goes to it. +### pin + +A register's name at the thing it points to: the names, bold, primary, and +a head in the target's region ink that touches the target. 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 | a stub 3 wide rising to the node's bottom edge, head 10 by 10; the first name left of the stub, the others right | -**Hex.** +A pin for every register whose value is exactly the row's or node's +address; three names, then a count. No box, no fill: the boxed names of +the last revision read as buttons. Mocks 9 to 11. -- Lower case, in groups of four from the right, half a character apart. -- An address is as long as it is: `28b4 1090`, `7ffe 970f 17b0`, - `100 1926`. No leading zeros, no `0x`: its ink says it is an address. -- A number that is not an address has `0x` once it has two digits, so that - `10` is never sixteen: see below. -- Decimal for what the source calls a number; both where a register may be - either. +### bracket -## The context (rev 2) +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. -Five panels, in the state they are in when `ztrace show FILE N` prints them. -Mocks [9](mock/09-context.png) and [10](mock/10-context-step.png) are -moments 71 and 72 of a recording of `targets/list`. +### tag -### Panel +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). -A tag one row high on `raised`: a 12-unit box 8 in (gold where the narration -is, a faint hollow elsewhere); the title, Go Medium 20; a note, Go 18, -ranged right. A 2-unit rule round the body; the body is the page. +## 2. Rows -### Registers +Every row is 24 high and one line. None wraps; what does not fit is cut at +its far end and says so. -Eighteen rows, in pwndbg's order: rax rbx rcx rdx rsi rdi rbp rsp, r8 to -r15, rip, flags. A name (dim) in a column of five characters; its value at -72 from the panel's edge; then its chain. +### chain -- rip: gold plaque on the name, gold ember across the row, the address in - code's ink and its name after it: `100 1926 reverse+22`. rip is never - "written". -- flags: the value, then the eight names. A set flag is upper case, bold, - bright, on a `raised` chip; a clear one lower case and faint - (pwndbg's `[ cf PF af zf sf IF df of ]`, without the brackets). One that - changed has the tick. -- Rows never reorder and none is hidden. +`address (points address)* (holds value)?` -### The telescope +- 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 tick sits before + 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. -One row a chain, read left to right: *this, which points to that, which -holds this.* +### reg -- **An address**: its digits in its region's ink. -- **Points to**: an arrow 30 wide, a 2-unit shaft and a head 8 by 10, faint. - pwndbg's `—▸`. -- **Holds**: the same arrow pointing back. pwndbg's `◂—`. What follows it is - not an address. -- **The end**: a number, a string, or nothing after a code address but its - name, 10 units on, in primary: `100 18b0 main+80`. Where there is no - symbol, the module: `libc+27781`. -- **A string**: in quotes, in string ink, with C's escapes. Cut to the room - left with `…` and no closing quote; never to fewer than six characters. -- **Depth** is the recording's (three by default: four addresses from a - register, five in a stack row counting the row's own). A chain that was - still a pointer where the recording stopped ends in an arrow and three - dots. So does one that runs out of row: the string is cut first, then the - chain ends early. Nothing is taken from the middle. -- **A chain that changes.** Only the link that changed is struck. If it is - the first, the register was written, and the links after it are followed - again one at a time, 4 frames apart: the telescope extends. If it is a - later one, memory changed under a pointer that did not, and the tick sits - before that link alone. -- **Its target, when the target is on screen.** No standing lines: thirty - chains would be a net. Four things tie them instead: - 1. the ink: blue is in the heap, yellow in the stack panel below; - 2. the digits: the same address is the row's own in the stack, the node's - in the lens; - 3. plaques: a register's name sits *at what it points to*, in the stack's - lane (`rsp`, `rbp`) and on a lens's nodes and rows (`rdi`, `rax`): - "who points here", up to three, then a count; - 4. one link, for the step in hand: from the row of the register just - struck, through the gutter, to the row or node it now holds, in the - region's ink, 3 units wide. It draws after the strike and goes with - the advance. ([Mock 10](mock/10-context-step.png).) +A name (dim) 12 in; its chain from 72; room to 12 from the edge. -### What a value shows as (rev 2) +`rip`: gold plaque on the name, ember 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 tick. (The value `0x206` is not drawn: the names are +the value.) -The tracer classifies; this is how each class is set. +### slot -| It is | Because | Shown | +A lane 112 wide for a `row` pin; the chain from 122, beginning with the +slot's own address in stack ink with `lead`; room to 136 from the right +edge, which belongs to the [`call`](#call) spans. + +### insn + +An instruction, pwndbg's way: what it is, and what its operands are now. + +| x | Column | | | --- | --- | --- | -| a pointer | it lies in a mapping | its address in the region's ink, and its chain | -| a code address | the mapping is executable | address, then `name+offset` in primary | -| a string | a pointer to printable bytes and a NUL | `"..."` in string ink | -| a digit | not a pointer, under 10 | `4` | -| a small number | not a pointer, 10 to 0xffff | `0x21` and its decimal after it, faint: `0x21 33` | -| a large number | not a pointer, larger | hex in fours with `0x`, primary | -| a small negative | within 4096 of 2^64 | `-1` | -| a file descriptor | a syscall's signature, or a variable's name and type, says so | the number, and faint what it was opened on: `3 "note"` | -| flags | eflags; an argument a signature calls flags | names: `O_RDONLY|O_CLOEXEC`; for eflags all eight, as above | -| a boolean | the debug info types it so | `true`, `false` | -| a character | the debug info types it so; a byte in a text view | its hex and the character: `0x41 'A'` | -| unknown | never observed | two dots | +| 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 | +| 180 | mnemonic | keyword, bold | +| 264 | operands | as the disassembler writes them, 24 characters; a jump's or call's target is an `address` in code ink | +| 564 | annotation | 25 characters; cut at its far end | -Decimal goes beside hex when a value is a small number and nothing says -which it is (registers, stack words, heap words). When the type is known -the type decides: an `int` is decimal alone, a pointer hex alone. In a -system call's rows a size or a count is decimal first. +| State | Draws | +| --- | --- | +| `current` | plaque, ember 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` | past the function's end: a rule above the row, everything faint, the next symbol's name in the annotation column | -### Disassembly +**The annotation**, by what the instruction does: -A row an instruction: the address in code's ink, its offset in the function -faint (`+22`, to match rip and the backtrace), the mnemonic as a keyword, -the operands plain, a jump's target in code's ink. The function's name is -the tag's note. +| 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 | -- The pc's row: gold plaque with a marker, gold ember across. -- Two rows above it are the instructions just run, with trail bars; the pc - is never the top row. -- **Under the pc, a row that says what its operand is**: `rdi + 8 =` and a - telescope from the address computed. Before the step it is where to look; - during it, its first link is framed as read or struck as written. -- A `syscall`: under it, on vellum, the call decoded, a row an argument, by - the argument's own name (`fd`, `buf`, `count`). +Mocks 9 to 11 show the read, the register-setter, the taken jump and +`outside`. Call, return, write and syscall annotations are not drawn. -### Stack +### line -Eight words from rsp, low addresses on top. A lane for the plaques of the -registers that point at each row; the row's own address in stack's ink; its -chain. Where the frame pointer says so, a faint note at the row's end: -`return address`, `main's saved rbp`. +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, ember across. `trail`: the bar, for the last three +other lines run. -### Backtrace +### bytes -A row a frame, newest on top: `#0` on a gold plaque, the name and offset, -the file and line. Three rows; a deeper stack ends in a count. +A hexdump row. Its runs come from the types of what the program's +pointers reach. -### Source +| 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, little-endian: a number ranged right in three characters; a pointer as `points` and its `address`; `NULL` dim; an allocator's run as a note in Go 18, faint | -The whole file, in mono 20 on rows of 24, a window on it kept so that the -current line is in its middle third. It scrolls by whole lines (0.4 s) and -never cuts. Line numbers faint, ranged right in three characters. A line -longer than the 67 characters the panel holds is cut with a faint `…`. +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. -- Current line: gold plaque on the number, gold ember across. -- Trail: the last three other lines run keep a 4-unit bar at the left edge, - gold cooling. +Marks are per run: `struck` (the paper solid vermilion, digits bold in +ink), `read` (a 2-unit frame 3 out), `held` (a tick in the gap at the +run's left). A struct wider than a row spans rows, and its bracket spans +them. -## The lens (rev 2) +### call -Everything the first pass drew that is not one of the five panels is a -lens: a list's nodes and arrows, a call tree, an array's cells, the heap to -scale, a string's bytes, a system call's crossing, the page map and the -timeline of calls. One at a time, in the panel at the top of the program -column. +One frame of the call chain, in two forms. -- It is drawn on the context's module (mono 20, rows of 24, values at 25) - and one size up when it is the subject. The first pass's sizes (cells of - 48, mono 30) are what it comes to under the camera at x1.5. -- **It carries the words it is made of.** A list's lens is its nodes and, - under them, the heap words that are those nodes, an address, a value and - a `next` a row. A tree's nodes carry the frame they are; an array's cells - sit over their bytes. -- **It is tied to the context** the way a chain is tied to its target: the - same address under a node as in `rdi`'s row; the registers' plaques on - the node and on its row; the same mark at the same instant in the lens - and in the words (read, struck, landed); and the step's one link. -- What happens to a node happens to its words first: the words are the - cause (`motion.md`, the cascade). -- **With nothing to draw**, the panel still holds what a recording has - beyond the five: the live heap, a chunk a row (address, size, its first - words as a telescope), or the named variables, a row each (name, type, - value by its class). They are the plainest lenses, and the default one - whenever a recording has them. +- `span`, on the stack: a bracket 14 in from the panel's right edge down + the slots that are the frame, and the function's name left of it, Go + Medium 18. `newest`: gold bracket, bright name. Older: rule and dim. A + frame that runs past the panel's last slot has no bottom serif. +- `row`, in a backtrace panel: `#n` (a gold plaque on the newest), the + name and offset in primary at 60, file and line in dim at 276. -The forms themselves are as the first pass drew them, in mocks 1 to 8: +## 3. Panels -| Lens | Mock | Its words | -| --- | --- | --- | -| list: nodes `[value | next]`, arrows in heap's ink, null a slash | [2](mock/02-list-insert.png), [9](mock/09-context.png) | the heap words, a node a row | -| call tree: circles, results on the shoulder | [1](mock/01-fib-recursion.png) | each node's frame in the stack telescope | -| array: cells, index tags, flights for a swap | [7](mock/07-sort-swap.png) | the bytes, where the array lives | -| heap to scale: chunks, bins, masks, a wedge into one chunk | [4](mock/04-malloc-glibc-musl.png) | the chunk's words | -| bytes: a grid of 8 with its text | [5](mock/05-memory-write.png) | themselves | -| a system call: vellum, the call decoded, the bytes crossing | [3](mock/03-syscall-write.png) | the registers that carried it | -| the far view: pages, system calls over time | [8](mock/08-far-view.png) | the mappings | +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; four when the lens is the +subject. `call` spans down its right edge: the backtrace, drawn on the +words that are each frame. rsp and rbp are pins in its lane. Reads the +stack words, and each frame's extent (the frame-pointer chain, or the +unwinder's CFA). + +### backtrace + +`call` rows, newest on top, four and then a count. A panel of its own only +in the `none` split, where there is room under the stack; in the others +the stack's spans carry it. + +### source -Those eight frames were drawn as whole frames; each is now what its lens -looks like with the camera on it. They have been redrawn in the new face -and with pointers in their regions' inks, and are otherwise the first -pass's. +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 title card and the legend ([mock 6](mock/06-title-legend.png)) are the -only frames with no context: no program is running in them. +### disasm -## Directing the eye in a full picture (rev 2) +Seventeen `insn`s in address order: the pc's, eight above, eight below. +Eleven (five, the pc, five) when the lens is the subject. -Everything is on screen, so nothing is found by being alone. In order of -how often they are used: +- Rows above the pc are the function's own instructions. Near its start + there are fewer, and the pc's row sits higher; the window stays full + from below. +- Past the function's end the rows are `outside`. +- 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. -1. **The cascade.** A step's effects arrive one place at a time, in the - order they were caused, 0.30 s apart (`motion.md`). Onset is the pointer. -2. **The gold thread.** One current mark a panel: the source line, the pc, - rip, frame #0, and the lens's current node. They move last, together. -3. **The strike**, the one solid warm thing in a frame of tints. -4. **The focus box.** The tag's box is gold in the panel the narration is - in, and only there. It is the old level rail, moved onto the frame. -5. **The step's link**: one arrow, for one step, from a cause to its effect - across panels. -6. **A veil** on the panels a named step does not touch (page at 50%, 0.3 s - in and out). For a beat, not a scene. -7. **The camera**, to read: +### lenses -| Scale | Mono 20 becomes | Frames | For | +A lens is the band across the top of the stage: **a drawing, and beside +it the pane the drawing is a view of.** + +| Lens | Drawing | Is a view of | Mock | | --- | --- | --- | --- | -| x1.5 | 30 | 1195 by 560 | a column, or the lens with the registers' names and first links | -| x2 | 40 | 896 by 420 | up to sixteen rows of one panel | -| x4 | 80 | 448 by 210 | one chain, one node and its words | +| `nodes` | boxes of a value and a pointer, arrows between them | a `hexdump` of the nodes' bytes, right half of the band | 9 to 11; 2 at camera scale | +| `array` | cells, index tags, 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, results on the shoulder | the `stack` panel: each node is a `call` span. The drawing has the band's whole width | 1 at camera scale | +| `syscalls` | the crossing: vellum, the call decoded | the `registers` that carried it, by `echo`. Whole width | 3 at camera scale | +| `pages` | the far view: pages, system calls over time | the mappings. Whole width | 8 | +| `hexdump` alone | bytes and their text | itself | 5, in its first-pass form | + +**What a new lens must provide** to fit the frame: + +1. A drawing that fits 856 by 116 (`beside`) and by 212 (`subject`), or + twice the width where it is a view of the stack or the registers. +2. The pane it is a view of, 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 arrive from + above, pointers from below.** +4. Each mark on its cells: `current`, `armed`, `struck`, `held`, `read`. +5. Its `establish`: how its elements rise from what they are drawn from. + +### nodes + +Boxes of 116 by 44, 28 apart: six fit the band's half (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: five beside, nine as subject. Rows in address order; a gap in the +addresses is one row holding `more`'s three dots and the count of rows +left out. Tag (the band's +right half): `its bytes`, the range shown, and the legend of runs: each +field's name in its bytes' ink, `malloc's`, `never read`. + +## 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 | +| `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; the part of the drawing made of them | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket over the node's address; 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 | always | no line | -The rules of `motion.md` hold: the target is framed first, everything else -fades, the move is 1.2 s, nothing else moves under it, and two seconds -without a change is the limit. The camera comes back to the whole frame -every time. It is a way of reading the context, not a place to be instead -of it. +`call` spans and `pin`s are ties too, the kind that need no line because +they sit on their target. -**Levels** are no longer layouts. Going from a line of C to the register it -writes to the bytes it stores is the cascade crossing the frame: source -line (fire), disassembly note (where), registers (strike), stack or lens -words (strike), lens (the idea changes). The viewer is never moved; their -eye is. +**Budget.** One `thread`, always. For a step, one `link` and one +`projection`. Never more than three drawn lines in the frame; a second +pointer or a second run in the same step gets `echo` and pins. -## Motion +**Routes.** A tie runs only in channels, with corners of radius 8 (6 for a +projection): -[`motion.md`](motion.md) is the direction. What density changes in it: +| Channel | Carries | +| --- | --- | +| the left margin, x 54 | the thread | +| the gutter's left lane, x 950 | a link, coming up from the registers | +| the gutter's right lane, x 962 | a projection, from the dump | +| a lens's bottom lane, 8 above its edge | a link, to the pin under its node | +| a lens's top lane, 4 under its tag | a projection, to the bracket over its node's address | + +A link stays below a lens's nodes and a projection above them, and each +has its own lane in the gutter, so the two cannot cross. A tie may cross +a panel's rule; it never crosses a letter, a digit or another tie. + +**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. -- A strike in the context: the arm is a 2-unit frame; the pulse goes out 3 - units, not 4; the fill cools to nothing and leaves the tick. -- A telescope extends link by link, 4 frames apart, each fading in over 6. -- A register's plaque slides to the row or node the register now points at - (0.4 s, `glide`), after the register is struck. -- The step's link draws in 0.4 s (`standard`) after the strike, and fades - over 0.3 s as the marks advance. -- The pace counter and the progress line are on the clock rule over the - caption, not in a head. -- Camera frames are those in the table above; x1.5 is the usual one. +## 5. The frame -## Legibility rules (rev 2) +| 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 | | +| margin | 1032 to 1080 | page | -- Mono 20 and sans 18 are the floor. Medium weight under mono 30. -- Whatever the narration names is also at 35 in the caption or at 30 under - the camera. -- Lines: 2 units is the thinnest (rules, a read's frame, an arrow's shaft - in a chain); 3 for a link and a lens's frames; 4 for a tick. -- A region is told by ink; a mark never is. No mark sits under coloured - digits except a strike, for its 0.6 s, and the gold ember of a current row. -- No alpha tints but the veil, no gradients, no glow, no grain. -- Dashes 12 on, 8 off; the hatch 5 on a pitch of 20. Nothing finer. -- Solid vellum is the kernel and nothing else. -- One gold mark a panel. One step's writes in vermilion at a time. -- Nothing is hidden to make room. A row that cannot hold its chain ends in - dots at its far end; a panel that cannot hold its rows ends in a count. +No data below 888: a player's controls cover it. + +**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, both columns): what it means, and the +bytes that mean it. The split is the one thing about the layout a scene +chooses. + +| Split | Band | 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; dump of 5 | 8 lines, 212 to 436 | 17, 448 to 888 | 212 to 652 | 8, 664 to 888 | in the stack | +| `subject` | 248, 48 to 296; dump of 9 | 10 lines, 308 to 580 | 11, 592 to 888 | 308 to 748 | 4, 760 to 888 | in the stack | + +**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 +lens takes six rows from the disassembly and four slots from the stack. + +| Of the frame | `none` | `beside` | `subject` | +| --- | --- | --- | --- | +| context | 68% | 56% | 48% | +| lens band (drawing and bytes, half each) | | 13% | 21% | +| caption band | 10% | 10% | 10% | + +### 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, under its right end. +- **`caption`**: one or two lines, Go 40 on 54, ranged left on the + margin; code in it is mono 35. Hex in it is unbroken too. +- **`veil`**: the page at 50% over the panels a named beat does not + touch; at 65% under the camera. +- **`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 | 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 to s+36 | +| `cool` | a struck value | s+36 to s+60, `glide`: in the context to nothing, leaving `held` for three steps (then out over 36 f); in a lens's cell to its bar | +| `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 lands with the head and settles (12 f); held; at the advance the line draws back into the pin over 18 f | +| `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, `standard`); only when it arrives does the part react (its own `read`, or `arm` and `strike`); out with the advance, 18 f | +| `travel` | a value or a tag going from one place to another | 30 f to 200 units, 36 f to 400, 48 f beyond; `glide` | +| `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 | +| `run` | steps that need not be read | 18 f a step, no arm, marks jump; 24 steps at most | +| `sprint` | steps to be got through | 4 f a step: only the current marks and the clock move. Each change of pace ramps at 0.6 of the step before | +| `establish` | a scene's opening | the state column, then the program column, then the band: 60 f and 30 f a panel. A lens's dump first; then each element rises from its row by `project`, 6 f apart in address order, and the lines go, leaving the quiet brackets | +| `scroll` | a `source` or `disasm` window | whole rows, 24 f, `glide`; marks ride with their rows | +| `relayout` | a change of split | 48 f, `glide`; nothing else moves under it | +| `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`; 120 f at most without a change; back | +| `say` | the caption | out 12 f, gap 6 f, in 18 f; it leads what it describes by 60 f, 120 f at a scene's first | + +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, 2.5 s across three +levels. + +## Composition + +**What may contain what.** + +- The stage holds the band and two columns. A column holds panels. A + panel holds a tag and rows, or (a lens) a tag and a drawing. A row + holds atoms. Nothing nests deeper. +- 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 + current mark moving before the hold. +- 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. +- 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/gen.py` draws 1 to 8 and `mock/context.py` 9 to 11; resvg renders -them; each has a `-480.png` beside it. +`mock/context.py` draws 9 to 11, one function a block under the block's +name; `mock/gen.py` draws 1 to 8. Each has a `-480.png` beside it. + +```sh +cd design/mock +python3 context.py && for n in 09-context 10-context-step 11-context-lens; do + resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done +python3 gen.py # 1 to 8, then resvg the same way +``` -| | Shows | After looking | +| Mock | Is | Blocks it shows | | --- | --- | --- | -| [9](mock/09-context.png) | **(rev 2)** the default frame at rest: moment 71, stopped in `reverse` at `mov rdi, [rdi + 8]` | the first draft's lens had plaques over its table's heads and a note over a column: nodes, addresses, plaques and words each got a row of their own | -| [10](mock/10-context-step.png) | **(rev 2)** the same, mid-step: `rdi` struck, its chain re-followed, the word it read framed in three places, its plaque moved, the link to its node | the link ran through the register's name like a strike-through, and ended in empty space: it now leaves from the panel's edge and lands on the row, which is framed whole. Chain arrows went from 24 to 30 wide: at 24 they touched the digits | -| [11](mock/11-context-lens.png) | **(rev 2)** the lens as subject: 432 tall, a size up | a note collided with a column head at the larger size and was dropped | -| [1](mock/01-fib-recursion.png) to [8](mock/08-far-view.png) | the first pass's frames: now the lenses, and the title card | redrawn in JetBrains Mono, with pointers in region ink and the legend remade: what happened in one row, what a thing is in the other | +| [9](mock/09-context.png) | `beside`, at rest: moment 71 of `targets/list`, stopped at `mov rdi, [rdi + 8]` | every panel; `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, allocator, unread and `pad`; `nodes` with pins under; `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; `projection` | +| [11](mock/11-context-lens.png) | `subject` | the band at 248, the drawing a size up, a dump of nine, eleven instructions, four slots | +| [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` panel with `call` rows. +- `insn` annotations for a call with its arguments, a return, a memory + write, a system call, `not taken`, a jump out of the window. +- `value` classes other than digit, small number and string. +- `armed`, `fault`, `attention` and the veil in the context. +- A `projection` for a write (vermilion). A `link` to a `slot`. +- A struct wider than one `bytes` row; a gap in a dump; text in a dump. +- `array`, `heap`, `calls`, `syscalls`, `pages` in the band. +- `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 11 is the recording's: every register and chain, the -instructions, the stack. The backtrace is read off the stack's return -addresses. The lens's heap words are what the chains and the program say -the heap holds; the recording, made under ptrace, has no allocations in it. +**The data in 9 to 11** is the recording's: registers, chains, stack, the +instructions and their lines. 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. -**At 480 wide** ([9](mock/09-context-480.png), -[10](mock/10-context-step-480.png)): no digit of the context can be read. -What is left is the two columns, four gold rows, the strike on `rdi` and -the link from it into the lens, yellow and blue as texture, and the caption -whole. In [11](mock/11-context-lens-480.png) the list's values can be read -as well. That is the phone's share, and the reason for the rule about the -caption. +**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 (rev 2) +## What this asks of the renderer -1. **Faces.** JetBrains Mono NL in four (Regular, Medium, Bold, Italic) and - Go in three. `sk.Face` has no medium mono today. -2. **A camera rest at 1.5**, with text shaped for its size there (mono 30, - an advance of 18), as it is at 1, 2 and 4. -3. **Many runs.** A context frame is about 700 separately inked runs of - text: every group of four hex digits is its own. Unsure whether `f.text` - at that count is comfortable in an export, or wants batching. -4. **From the recording**, which I have not checked beyond `ztrace show`: - - the instructions *before* the pc (from earlier moments, or decoded - backwards), for the two trail rows; - - an instruction's memory operand as data (base, index, displacement), - so the note under the pc can compute and follow its address; - - a backtrace: `show` names return addresses in the stack but prints no - frames for a ptrace recording; - - a lens's words when nothing recorded an allocation (`-w`, or the - agent). -5. Underlines, ticks and frames are rects; the scrolling source wants - `f.clip`; chain arrows are 8-pixel polygons and rely on the supersampling. +1. **Faces.** JetBrains Mono NL in four and Go in three; `theme.font.mono` + is still Go Mono. +2. **Places.** `ties.Place` has register, word, node, source and pc. The + thread needs every run of the current line's instructions, not the pc + alone; a projection needs a run of bytes in the dump and a *part* of a + node (its value, its pointer half); a link needs the pin's place. +3. **From the recording**: + - the line of each instruction in the window, for the `line` column + and the thread; + - which instructions ran between two stops, for `ran` rows when + stepping by line (or a recording by instruction); + - each frame's extent on the stack, for `call` spans; + - the bytes of a lens's region at each stop, so that allocator rows + are read and not guessed; without it they are `unread`, honestly; + - a callee's prototype, for the number of arguments under a call. +4. **Runs.** Mock 10 is 351 runs of text, 174 rects and 63 paths. An + address is one run now (two with `lead`). +5. A camera rest at 1.5, with text shaped for mono 30 there. 6. Still open from the first pass: dashed strokes from `sk.draw`. ## Token changes -For `anim/src/theme.zig`. Nothing in `time` changes but the two additions -at the end. +For `anim/src/theme.zig` as it stood when this was written. "Was" is what +is in the file. | Token | Was | Is | | --- | --- | --- | -| `font.mono` | Go Mono, `Go-Mono.ttf` | JetBrains Mono NL, `JetBrainsMonoNL-Regular.ttf` | -| `font.mono_medium` | | `JetBrainsMonoNL-Medium.ttf`: mono under 30 | -| `font.mono_bold` | `Go-Mono-Bold.ttf` | `JetBrainsMonoNL-Bold.ttf` | -| `font.mono_italic` | `Go-Mono-Italic.ttf` | `JetBrainsMonoNL-Italic.ttf` | -| `size.mono.context` | | 20 | -| `size.mono.small` | 25: gutters | 25: a lens as subject, a lens's values | -| `size.mono.data` | 30: anything read | 30: the context under the camera | -| `size.sans.micro` | 22 | 18 | -| `size.sans.tag` | | 20 | -| `size.sans.label` | 28 | 28, in title cards only | -| `size.min_read` | 28 | 20 | -| `size.min_any` | 22 | 18 | -| `canvas.head`, `head_baseline`, `head_rule_y` | 48 to 96, 81, 104 | removed | -| `canvas.stage` | y 120, h 768 | y 48, h 840 | -| `canvas.clock_y` | | 900 | -| `canvas.row_gap` | 24 | 12 | -| `layout.solo`, `duo`, `duo_even`, `trio`, `trio_stack`, `trio_hero`, `quad`, `far`, `crossing` | | removed | -| `layout.program`, `layout.state` | | `cols(0, 6, 0, 840)`, `cols(6, 6, 0, 840)` | -| `layout.split.none` | | source 21 rows, disassembly 10 | -| `layout.split.beside` | | lens 312, source 12, disassembly 6 | -| `layout.split.subject` | | lens 432, source 8, disassembly 5 | -| `layout.state_rows` | | registers 18, stack 8, backtrace 3 | -| `color.region.stack` | | `f2d675` | -| `color.region.heap` | | `86b6ff` | -| `color.region.code` | | `ff8f9a` | -| `color.region.data` | | `d59cf5` | -| `color.string` | | `b5e8c8` | -| `color.code.literal` | `c8f0d8` | `b5e8c8` | -| `color.veil_alpha` | 0.65 | 0.50 for a beat's veil; 0.65 under the camera | -| `Role.pointer`, `Form.arrow` | orchid frame and arrow | removed; `Role.link`: region ink, `Form.thin_arrow` 3 wide | -| `mark(.write)` held, in the context | ember and bar | `metric.context.tick` | -| `metric.context.row` | | 24 | -| `metric.context.tag` | | 24 | -| `metric.context.pad` | | 6 above and below the rows, 12 at the sides (8 in the stack) | -| `metric.context.name_w` | | 60: five characters | -| `metric.context.chain_x` | | 72 | -| `metric.context.arrow_w` | | 30, for both arrows of a chain | -| `metric.context.group_gap` | | half an advance: 6 at mono 20 | -| `metric.context.tick` | | 4 wide, the row less 6 tall | -| `metric.context.plaque_h` | | the row less 4 | -| `metric.context.read_frame` | | 2 | -| `metric.context.pulse_outset` | | 3 | -| `metric.context.string_min` | | 6 characters | -| `metric.context.source_chars` | | 67 | -| `metric.lens.node` | 180 by 72 | 116 by 44 beside, 124 by 64 as subject | +| `font.mono`, `mono_bold`, `mono_italic` | Go Mono | JetBrains Mono NL Regular, Bold, Italic | +| `font.mono_medium` | | `JetBrainsMonoNL-Medium.ttf`: all mono under 30 | +| `metric.context.pad` | 6 | 4 | +| `metric.context.group_gap` | 6 | removed: hex is unbroken | +| `metric.context.lead_alpha` | | 0.6: the shared digits of a column of addresses | +| `metric.context.pad_alpha` | | 0.45: a word's padding bytes in a dump | +| `layout.registers` | 18 rows | 17: the flags are in rip's row | +| `layout.stack` | 8 | 8; 4 in `subject` | +| `layout.backtrace` | 3, always | 4, in `none` only | +| `layout.band` | | y 48, full width: 152 `beside`, 248 `subject` | +| `layout.split.none` | source 14, disasm 17 | the same; registers, stack 8, backtrace 4 beside them | +| `layout.split.beside` | lens 312 in the program column, source 8, disasm 10 | band 152; source 8, disasm 17; registers, stack 8 | +| `layout.split.subject` | lens 432, source 5, disasm 8 | band 248; source 10, disasm 11; registers, stack 4 | +| `layout.dump_rows` | | 5 `beside`, 9 `subject` | +| `metric.insn` | | columns at 2, 31, 40, 134, 180, 264, 564; operands 24 characters, annotation 25 | +| `metric.bytes` | | bracket 7, address 18, bytes from 132 on a pitch of 30 with 12 after the eighth, reading 640 | +| `metric.slot` | | pin lane 10 to 112, chain 122, room to 136 from the right | +| `metric.table.flag` | 60 by 36 | chip 32 by 20, pitch 42, ranged right in rip's row | +| `metric.pin` | | `row`: head 9 by 12, 5 after the names; `under`: stub 3 wide, the mono size and 10 long, head 10 by 10, names 9 either side | +| `metric.bracket` | | `quiet` 2 and 5; `tie` 3 and 6 (thread 7) | +| `metric.plaque` | 40 high, pad 12 | gold only: 54 (rip), 50 (a line number), 24 (the pc) wide, the row high | +| `metric.node` | 180 by 72, pointer 72 | 116 by 44, 28 apart; 124 by 72, 22 apart as subject; pointer half 48; origin 10 | +| `metric.lens.lane` | | 4 under the tag (projections); 8 above the bottom edge (links) | +| `metric.tie.thread_x` | | 54 | +| `metric.tie.lanes` | | 950 (link), 962 (projection) | +| `metric.tie.radius` | | 8; 6 for a projection | +| `stroke.tie` | | thread 3, link 3, projection 2 | +| `color.well` | | `101a48` | +| `Role.pointer` | orchid frame and arrow | removed. `Role.link`: region ink, 3 wide | +| `mark(.write)` held | ember and a 6-unit bar | in the context a tick, 4 wide; in a lens's cell a bar, 4 high | +| `color.veil_alpha` | 0.65 | 0.50 for a beat; 0.65 under the camera | | `metric.max_rows` | 10 | removed: nothing is hidden | -| `camera.scales` | 1, 2, 4 | 1, 1.5, 2, 4 | -| `time.unroll` | | 4 f (0.0667) between links re-followed | -| `time.link` | | 0.40 to draw, 0.30 to go | +| `time.link` | draw 0.40, go 0.30 | draw 0.40 (0.60 over 400 units), settle 0.20, back 0.30 | +| `time.project` | | bracket 0.10, draw 0.30, out 0.30 | +| `time.establish_rise` | | 0.10 between a lens's elements | +| `size.mono.value` | 35 | 35 in a caption; a subject lens's values are `flight`, 45 | -## Implementation order (rev 2) +Unchanged and already there: the palette, region inks, `time.cascade`, +`strike`, `read`, `unroll`, `run`, `sprint`, `ramp`, the camera's scales. -1. The faces and `size.mono.context`; the one-row panel. -2. **The telescope**: an address in its region's ink, the two arrows, the - end by class, the cut at the row's end. It is three of the five panels. -3. Registers, stack, backtrace: the state column, at rest. -4. Source (scrolling) and disassembly with its note: the program column. -5. Marks at density: strike, tick, read frame, the telescope extending. - The cascade of `motion.md` over these five panels. -6. Plaques at what registers point to, in the stack and then in a lens. -7. The lens panel and its three splits; the list first, with its words. -8. The step's link; the veil; the camera at x1.5. -9. The other lenses, from what exists: tree, array, heap, bytes, crossing. +## Building it -Shader effects worth having: still none. +1. Atoms: `address` (unbroken, `lead`), `arrow`, `value`, `mark`, `pin`, + `bracket`. The gallery starts here. +2. `chain`, then `reg` and `slot`: the state column 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: |
