summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md137
1 files changed, 121 insertions, 16 deletions
diff --git a/design/README.md b/design/README.md
index 7428b84..bf6866d 100644
--- a/design/README.md
+++ b/design/README.md
@@ -64,7 +64,7 @@ this table.
| | [`tag`](#tag) | a panel's title bar | `focus`; `note` or `legend` |
| | [`width`](#width) | an access's size in byte cells, where no register says it | 1, 2, 4, 8 cells; a count past 8 |
| 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop; opens a `loupe` |
-| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) |
+| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`); `parts`: its eight bytes and the names its low ones go by |
| | [`slot`](#slot) | a word of the stack and its chain | pins; `free` |
| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside`, `waiting`, `pass`; the annotation `tied` (the default) or `whole` |
| | [`line`](#line) | a line of source | `current`, `trail`, `waiting`; wide numbers |
@@ -93,7 +93,8 @@ this table.
| | [`pair`](#pair) | two runs of one program against each other, a seam between them | `only here`, `differs`; each run's frame as bytes, an ASan run's shadow beside its rows |
| | [`map`](#the-map-and-the-minimap) | the working frame unfolded, every panel whole: 3840 by 2160 | the key |
| | [`minimap`](#the-map-and-the-minimap) | a pane's whole column of the map, small, in a strip at its right | its window, marks, `flash` |
-| | [`clock`](#clock-and-caption) | where in the recording | |
+| | [`clock`](#clock-and-caption) | where in the recording | its label: the chapter |
+| | [`chapter`](#clock-and-caption) | a part of one scene with a title of its own, opening on the last picture of the part before | its title said at its seam; its name the clock's label |
| | [`column`](#column) | the second form a scene is composed in: the panes a beat is about in one column, its narration in the other | the `shelf` of folded panes; text on the right, or on the left while the program column is empty |
| | [`bubble`](#column) | a piece of narration placed in the frame, level with what it speaks of | `beside`, `below`, `above`, `on`; newest, older; its `stem` |
| | [`caption`](#clock-and-caption) | the narrator | |
@@ -102,10 +103,11 @@ this table.
| 6 verb | [`fire` `arm` `strike` `cool` `read` `extend` `link` `project` `touch` `carry` `aim` `travel` `follow` `advance`](#6-verbs) | what one block does | |
| | [`open` `close`](#6-verbs) | what a loupe does | |
| | [`descend` `cross` `ascend`](#6-verbs) | what a descent does: a call followed down, a system call, a return | |
-| | [`regroup` `ink` `enlarge` `column` `frame up` `decode` `align`](#6-verbs) | what building a view does (the introduction) | |
+| | [`regroup` `ink` `enlarge` `column` `frame up` `decode` `align` `unpack` `pack`](#6-verbs) | what building a view does (the introduction) | |
+| | [`fold`](#6-verbs) | what the registers do: the quiet ones into their cells, three to a row (on a beat, or in a `dive`) | |
| | [`leave` `turn` `reach` `unfold`](#6-verbs) | what a graph does: a block left along an edge, a loop's turn round its ring, a block or an edge reached the first time, a fold opening | |
| | [`dive` `surface` `flash` `unroll` `roll`](#6-verbs) | between the map and the working frame; a pane and its whole column | |
-| | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | |
+| | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say` `title`](#6-verbs) | what a frame does; `title`, what a scene in chapters does at a seam | |
## 0. Tokens
@@ -427,6 +429,30 @@ 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.)
+**`parts`**: a register's value as its eight bytes, and the names its low
+bytes go by, for a beat that says so: code names a register by its parts
+(`mov edi, 0x10` writes rdi's low four bytes, `xor eax, eax` rax's), and
+the panel shows the whole register, so where the narration ties the two
+the row opens in place ([mock 59](mock/59-regs-parts.png); the
+introduction's II5). It is the regroup's idea read the other way: a word's
+digits are its bytes, and the low ones are on the right.
+
+| Row | Drawn |
+| --- | --- |
+| the register's | its name at 12; from 72 its eight bytes as a dump's (`byte`: two digits in 24, a pitch of 30, no gap), the high byte first as the number is read, so its low bytes are on the right; the zero bytes over its highest non-zero one at 45% toward the page (`pad`). Its chain is not drawn while it is open |
+| a part's, one under it for each, widest first | a 2-unit bracket in `dim` under the bytes the part is, ranged right with the low end, its serifs 11 up toward them, 3 out from the first byte and the last; the part's name ranged right 10 before the bracket's left end, mono 20, `dim`: so each name stands where what it names begins. rax: `eax` 4, `ax` 2, `al` 1 (rbx, rcx, rdx likewise); rsi: `esi` `si` `sil`; rdi: `edi` `di` `dil`; rbp: `ebp` `bp` `bpl`; rsp: `esp` `sp` `spl`; r8 to r15: `r8d` `r8w` `r8b`. `ah` (the second byte of the first four) only when an instruction names it |
+
+Marks: the part an instruction names is framed as read with its operand,
+its own row and its bytes in the register's row together (an echo, 6 f); a
+write strikes the bytes whose value changed and no other, as a dump's
+(`09` to `10`: one byte), and the row's annotation with them. A write to a
+4-byte part zeroes the four above it, which strike where they were not
+zero. One register opens at a time, in a walked step or a rest, never at a
+run; it opens and closes by [`unpack` and `pack`](#6-verbs). The rows
+under it make room and close up again: the panel grows by three rows while
+it is open (the state column under the registers must have them; in the
+introduction it is empty then).
+
### slot
A word of the stack, pwndbg's way and a little more.
@@ -724,7 +750,12 @@ its ink, and a pointer's chain cut at once to `more` (`r12 7fffffffee38 →
…`): its hops are on the map, whole. A quiet register a step reads is
framed as read in its cell; one a step writes was never quiet (a scene
with a `continue` changes them all, and folds none). The set is the
-scene's, chosen once: no row comes or goes while it plays.
+scene's, chosen once: no row comes or goes while it plays. A scene that
+builds the panel shows every register a row first and folds the quiet
+ones on a beat of its own ([`fold`](#6-verbs)), after which the set holds:
+the introduction builds it so in its chapter II, and its four chapters
+share one set (rax rcx rsi rdi, rbp rsp, which II's call and continue
+change; ten folded into four rows; 11 rows), as its clock is one.
The panel is as tall as its rows: sort moves eight (rax rcx rdx rsi rdi,
and rsp rbp rip) and folds nine into three rows, 11 rows, 296 high; the
@@ -787,7 +818,7 @@ to the stack's top.
- 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. A scene may hold it the same way
- while a frame is made: the introduction's chapter II holds it from its
+ while a frame is made: the introduction's chapter III holds it from its
first picture with four `free` words over rsp, enough for `push rbp` and
`sub rsp, 0x18`, so that only pins move and no row.
@@ -1528,7 +1559,7 @@ that leaves its window takes it away. `drawn` is a standing aim the beat
itself introduces, with no step to draw it: it draws as a step's does, head
first at full ink (18 f), the row's address framed as the head lands (6 f),
and falls to the standing 60% only when the next step begins (the
-introduction's return address, II3 to II4). Route: out of the word's panel's
+introduction's return address, III3 to III4). Route: out of the word's panel's
left rule level with it, the gutter's left lane (x 950), onto the
disassembly's (or a descent window's) right rule level with the row, its head
10 by 10 ([mock 57](mock/57-aim.png)).
@@ -1717,7 +1748,7 @@ named band carry their addresses, and the bands their sizes.
| the magnification | two 2-unit `rule` lines from the cluster's line on the whole (at its right edge) to the box's left corners. Nothing else is drawn between the whole and the boxes |
| the names | right of the box, from 64 past it (the leaders' room). A row for each edge of a named band: its address in mono 20, in the ink of the band it bounds, and a leader (2, `rule`) from the edge, 8 out, straight to 20 short of the address, 12 in. Between two edges a row for the band, indented 24: its permissions and its size (`dim`, ranged right 132 in), and its file in primary at 252 (`[stack]`, `libc.so.6`); a file of several named bands once, on a `quiet` bracket over their rows. Rows 24 apart, each as near its edge as the others let it (crowded rows pooled round their mean), inside the box's share of the stage; a leader never crosses another, as the rows keep the edges' order |
| what is named | the program by segment: each of its mappings a band with its two addresses, permissions and size, under a bracket with its name, because the scenes point into them (its code, its data). Every other file once: its mappings as one (an anonymous mapping after a file's data, its bss, with it; the vDSO with its data), its start, stop, size and name, its permissions where they are one (`rw-` for the stack and the heap), and where they differ, each part's written inside its band, centred, where the band is 28 tall. A band under 6 tall is drawn and not named (an anonymous page; in mock 34 the vDSO) |
-| live | rsp an `under` pin in the stack's band; rip a row pin at the end of its band's row (`◂ rip`). In the introduction's first chapter neither: there are no registers yet |
+| live | rsp an `under` pin in the stack's band (rbp's name on it where rbp is in the same pixel, names keeping their sides); rip a row pin at the end of its band's row (`◂ rip`). Each comes on its beat with its register's value framed as read and its band and the band's row framed (`ink`'s echo), and stands while `segments` does. In the introduction's first chapter neither: there are no registers yet; its second brings them (II2, II3; mock 58) |
| a dump's place | in the introduction, where the dump the scene has built stands beside it: a `tie` bracket on the dump's rows, and a [`link`](#4-ties) in the stack's ink from the bracket's top, up into the stage's top margin (y 56), across, and down onto the stack's box at the dump's address, its head on it. It draws in its own beat (the dump's addresses take the stack's ink as its head lands, never before) and then stands, quiet (60% toward the page), while both are on screen. For a camera's visit, where the dump is still far thinner than a unit, its place is marked on the box: a 2-unit tick across it in the stack's ink at the dump's address, the dump's size over it (`128 bytes`) left of the link's head |
| `ink`'s echo | the band a word points into, framed as read inside the box (2 units, 4 in from its sides, 6 over and under the band), and that band's row of names framed with it |
@@ -1973,6 +2004,23 @@ caption's and the clock'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".
+ A scene in chapters has one clock for its one recording, counted from the
+ recording's first stop and only forward; it comes with the first thing on
+ screen that shows a moment's state of the CPU (the introduction: its
+ registers, II2), and before that there is none. Its **label**, ranged
+ right 24 left of the count (alone, at 1856, where there is no clock
+ yet), is the chapter: its numeral and name, Go 18, `faint`
+ (`II registers`), crossfading at each seam (12 f, secondary): where in
+ the video, as the count is where in the recording.
+- **`chapter`**: a part of one scene with a title of its own, opening on
+ the last picture of the part before (the introduction's four). Its title
+ is said, not carded: in the caption's place, one line, Go Medium 40, its
+ numeral `faint` and its name `bright` (`II Registers`), up its reading
+ time as a caption is, over the picture, at the chapter's seam
+ ([`title`](#6-verbs)); its name stays as the clock's label. A chapter
+ ends when its last text is read; it holds no 2 s of its own, the seam is
+ its close. The video's chapter marks are its titles' frames ([mock
+ 62](mock/62-seam.png)).
- **`caption`**: one or two lines of at most 64 characters, Go 40 on 54,
ranged left on the margin; code in it is mono 35. Hex in it is unbroken
too. What a scene author checks, characters counted as shown:
@@ -1982,7 +2030,7 @@ caption's and the clock's.
| on screen, from arrived to leaving | at least 1.5 s + 0.06 s a character (90 f + 3.6 f) |
| on screen | at most 12 s; a longer stretch wants a second caption or a shorter scene |
| before the first step it describes fires | 60 f after it has arrived; 120 f for a scene's first |
- | a scene's first | arrives at 1.0 s; the first step fires by 4.0 s (5.0 s when the scene opens on the map and dives) |
+ | a scene's first | arrives at 1.0 s; the first step fires by 4.0 s (5.0 s when the scene opens on the map and dives); in a scene in chapters the first chapter's title comes first (0.1 to 2.6 s) and its first text after it, and the first step still fires by 4.0 s |
| changes | only in a rest, never under a moving thing |
| names | only what is on screen at the pace it plays: no register a run veils, no step that has not happened or that played more than its 60 f lead ago; and nothing before it has been shown, in a caption or a label (a dump's header, a tag): the introduction's first bytes are `128 bytes at 7fffffffebc8`, not the stack's, until the stack is on screen |
| checked | by the instruments' CAPTION ([motion.md](motion.md#the-instruments)) |
@@ -1993,7 +2041,8 @@ caption's and the clock's.
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.
+ The only frames with no context. A chapter's title is not one: it is
+ said over the picture it grows from.
- **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.
@@ -2189,7 +2238,7 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves:
| `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. **On a beat** the caption names, with no step (rsp in the introduction's II2, rax in its III3): the register framed as read (6 f), the line 6 f after (36 f, `standard`, the name riding its head), held as the beat says, then drawn back toward its head over 18 f with the register's frame, the head fading over the draw-back's last third: never gone in one frame |
+| `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. **On a beat** the caption names, with no step (rsp in the introduction's III2, rax in its IV3): the register framed as read (6 f), the line 6 f after (36 f, `standard`, the name riding its head), held as the beat says, then drawn back toward its head over 18 f with the register's frame, the head fading over the draw-back's last third: never gone in one frame |
| `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 |
| `touch` | the current row and the stack word it reads or writes (`tied`) | right after the fire, before anything the word causes: the line draws from the row's end across the gutter to the word's row, head first, 12 f (18 f when its leg is longer than six rows), `standard`; only when the head has landed is the word armed (a write: 12 f, then struck) or framed (a read, 6 f); only after that does what follows from the word move (a register it fills, rsp's pin climbing onto a pushed word, a span, a role). Held to the advance; drawn back into the row with it, 12 f, or (with `carry` on, for a load) as the carry leaves the word. A store of the value the word already held: the head lands, the arm's frame comes and goes and nothing is struck (in the introduction, where the push is the lesson, it is struck: [motion.md](motion.md#a-word-touched)). A word the window must scroll to: the scroll first, then the touch. At a run and a sprint none: the names stand, and the marks are the run's |
| `carry` | a value's way from its source to its destination (`carry = .arrow`; `.after_touch`: a store's touch first, then its carry) | the source framed `read` first (a register 6 f; a word by its touch); then the arrow draws from it to the destination, head first, 18 f (24 f past eight rows), `standard`; on its landing the destination is armed (12 f) and struck; the arrow draws back as the strike lands (18 f); only then what follows (a link from the register filled, a pin's travel). At a run and a sprint none |
@@ -2198,7 +2247,7 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves:
| `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. **rsp's and rbp's pins** are the stack's event and are given time: 24 f to the next row and 6 f a further row, 48 f at most, `glide`; the amount on the pin from its first frame, counting as it crosses each row (`rsp -8`, `-10`, `-18`, in write's vermilion, bold; in the introduction `-0x10`, `-0x18`, as its offsets are written: [slot](#slot)), held to the advance and then crossfading to the bare name (12 f); each row it reaches gained (brightening from `free`, 12 f, from the frame the pin's head reaches it, its role fading in with it) or released (to `free`, 12 f); the bracket over the rows crossed drawing with it; the newest span's end riding it; the register struck as the pin lands, and the row's amount with it. rbp's flight to rsp's row: the same, the names meeting in pwndbg's order (rsp slides aside, 12 f, before rbp lands). At a run: 8 f and 2 f a row, 16 f at most, drawn over the veil (the pins, the bracket, the span and the rows' gain or release stand clear of it; the rest of the stack stays veiled), no amount; at a sprint, on the map, rsp is the edge of the stack column's newest frame, moving with each moment (4 f), the spans growing and shrinking with it |
| `open` | a loupe, from a pointer | the pointer's hop framed `read` (6 f); the stem draws from it to the loupe's place, head first, 18 f (30 f over 600 units), `standard`; the loupe rises with the stem's head: it fades in over 12 f from 8 units lower, its shadow growing from nothing to its offset (18 f, `standard`); the target's bright frame lands 6 f after. From a pointer inside a loupe the same, over it, and a third closes the first as it starts. In the slot of the level that read the pointer, or on a beat the caption names |
| `close` | a loupe | the deepest first: its stem draws back into its pointer (12 f) and the loupe sinks, fading out over 12 f as it falls 8 units and its shadow shrinks; with the advance of the step it opened in. A loupe the narration keeps across steps closes at each advance and opens again in the idea's slot of the next step that concerns it (36 f, as `open`): the steps between are not drawn under it. Open 120 f without a change is the most |
-| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and each pane's column of the map becomes its minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; on the same move the rest of each window's column (the map's panel it is a window on) squeezes into its pane's strip: from its place at half size to the strip's rect, its width and its height each on its logarithm (to 36 of 880, and 4 of 24 a row), so the text thins to strokes as it lands, the window's outline riding on it to become the strip's window; the map's parts no pane takes (the backtrace, the key, the memory round pointers, a loupe's panel) fade where they are, 24 to 72. On the same move the registers' window (the panel whole on the map, every chain) folds as it lands: each quiet register's row glides into its cell, three to a row, its chain past the first hop fading over the move's first 24 f, so that the panel arrives at its height in the frame. 72 to 96: the drawing, whose sizes may differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: each squeezed column crossfades into its strip's strokes; the frame's tags, rules and lanes fade in; the veil goes with the last of the map. 96 to 132: still (mock 20) |
+| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and each pane's column of the map becomes its minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; on the same move the rest of each window's column (the map's panel it is a window on) squeezes into its pane's strip: from its place at half size to the strip's rect, its width and its height each on its logarithm (to 36 of 880, and 4 of 24 a row), so the text thins to strokes as it lands, the window's outline riding on it to become the strip's window; the map's parts no pane takes (the backtrace, the key, the memory round pointers, a loupe's panel) fade where they are, 24 to 72. On the same move the registers' window (the panel whole on the map, every chain) [`fold`](#6-verbs)s as it lands, on the move's 72 f, so that the panel arrives at its height in the frame. 72 to 96: the drawing, whose sizes may differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: each squeezed column crossfades into its strip's strokes; the frame's tags, rules and lanes fade in; the veil goes with the last of the map. 96 to 132: still (mock 20) |
| `surface` | from the working frame to the map | the dive backwards, a little quicker: 0 to 12 the tags, rules and lanes fade out and each strip's strokes become its column's text; 12 to 84, `glide`, each pane shrinks into its window on the map as its strip unfolds into the column round it, the map's other parts fading in where they are; 84 to 96 the veil lifts; then the map is still 36 f before anything plays on it |
| `flash` | a pane's minimap, at a mark its window does not show | a ring 8 across in the mark's colour, on the mark's row in the strip, draws out to 14 and is gone, 12 f, with the mark's own strike or read |
| `unroll` | a pane, to its whole column, for a beat, without leaving the frame ("the whole function", "the whole stack") | the strip's column grows out of the strip over the pane and the panes under it (veiled, 18 f), to the stage's height or the column's, a row of the map's 4 units scaling up on the logarithm to as many as fit (sort's 79 rows of text in 840: 10 a row, shapes and inks; a 22-line file at 24, readable), `glide`, 36 f; the window's outline rides from the strip to its place in the column; the pane's own rows are that window, so nothing appears or vanishes: they are the column's rows round the outline. Held while the caption needs it (60 f at least). `roll` is the reverse, 36 f: the column shrinks back into the strip, the outline lands as the strip's window, the panes under it unveil. A far jump in the same column is `unroll`, the window travelling to its new place along the column (24 f, `glide`), and `roll` |
@@ -2216,10 +2265,14 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves:
| `frame up` | a panel arriving round rows already built | its rule draws round them (12 f), then its tag fades in (12 f): the last thing, never the first |
| `decode` | an instruction's bytes becoming its row | the bytes of one instruction gather (12 f), the mnemonic and operands fade in beside them (12 f), and the bytes dim; the row then travels to its place (`glide`, 24 f) |
| `align` | the stacked program column to `aligned`, and back (`stack`); one form of `aligned` to the other | the band and the state column fade out (12 f); the panel widens to both columns (24 f, `glide`); the source's lines glide to their heads and the instructions glide in under them (36 f, rows making room), each instruction from its row in the disassembly to its row under its line; the heads' paper and rules fade in last (12 f). `stack` is the reverse. `interleaved` to `columns`: the addresses and instructions glide right into the instruction column (24 f, `glide`), then every row glides to its height in the new form, each line level with its run's first row (24 f, `glide`); the rules move with their groups; the lines with no code fade into the room made for them (12 f). Back, the same in reverse, the no-code lines first |
+| `unpack` | a register's row, into its [`parts`](#reg) | the rows under it make room (18 f, `glide`); its value spreads into its eight bytes, the pairs opening apart and the zeros in front coming in at `pad` (12 f, `glide`); the parts' rows come in widest first, each its bracket and its name (12 f, 6 f apart). Walked around a step that names a part ([chart](motion.md#a-registers-parts)); never at a run |
+| `pack` | a register's parts, back into its row | after the step's cool: the parts' rows fade (12 f); then one move, the bytes closing into the value as [`value`](#value) writes it while the rows under it close up (24 f, `glide`) |
+| `fold` | a registers panel, its quiet registers | each quiet register's row glides into its cell, three to a row on a pitch of 285, in pwndbg's order, its chain past the first hop fading over the first 24 f; the rows under them (rip's) glide up with them; then the rule over the first folded row draws (12 f): 36 f, `glide`, on a beat of its own (the introduction's II8). In a `dive` the same, on the dive's move; backwards only in a `surface`, on its way to the map |
+| `title` | a chapter, at its seam | from e, the frame the chapter before has its last text read: still 30 f; its texts leave together (12 f); the title arrives in the caption's place (18 f, rising 8), the clock's label crossfading 6 f after; still 60 f; the chapter's opening under it; the title leaves at its reading time or the opening's end, the later; the first text 6 f after. A pause of 2.1 s, e to e+126 ([chart](motion.md#captions-opening-closing)). The scene's first chapter: the title at 6 f, its first step still by 240 |
| `arc` | a pointer to a row of its panel | written: with the arm (s−12) the old arc goes dashed; from s+6 it fades (12 f) while the new one draws from the pointer's row along its lane to the target, head first, 12 f, `standard`, at full ink; with the cool at the advance it quiets to standing (24 f). Read: to full ink with the read (6 f), back with the advance. Overwritten with a target off the panel or NULL: it fades from s+6 (12 f). A lane change glides 12 f. Scrolled: it rides its rows, fading as its target leaves. At a run 8 f, at a sprint none |
| `advance` | the current marks | last. The thread, the plaques and rip move together: 12 f to an adjacent row, 24 f up to eight rows, `standard`; farther, out and in over 6 f. A taken jump's line draws in the jump lane with it |
| `cascade` | a step | `fire` (12); then its effects a level at a time, 18 f apart: CPU (`reg`s, the pc's annotation), memory (`slot`s, `bytes`; under `tied` the touch first), 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. A read is a cause, not an effect, and goes before what it fills: a load's word is reached and framed in the first slot (18), the register it fills struck in the next (36). Under `tied` the order is the instruction's own, cause to effect, and nothing downstream is armed or marked while what is upstream of it has not shown: the row fires; the touch leaves it; the word reacts on its landing; then what follows from the word (a register filled, rsp's pin onto a pushed word, the span, a role); then the window follows. A step that moves rsp or rbp and touches no word (`sub rsp`, `mov rbp, rsp`) has the pin's travel as its effect, the register struck as the pin lands |
-| `continue` | a stop far from the last: a breakpoint, not a step. Where the windows' new places are farther than their own heights (another function, another file), it is told on the map: `surface`, the jump there, `dive` | `fire` on the line it leaves from; then the levels as in a `cascade`, but CPU is a wave: every register that changed is struck 2 f after the one above it, in pwndbg's order, the fill in over 6 f, no arm and no pulse (a dozen pulses at once are a flash, and a dozen arms a crowd); memory: the stack's window scrolls or fades to its new place, and the [backtrace](#backtrace)'s frames leave, slide and arrive; the idea; hold 36 f after the last strike; `advance`, the source and disassembly fading through if far; rest. Its marks are only on what was on screen to change |
+| `continue` | a stop far from the last: a breakpoint, not a step. Where the windows' new places are farther than their own heights (another function, another file), it is told on the map: `surface`, the jump there, `dive` | `fire` on the line it leaves from; then the levels as in a `cascade`, but CPU is a wave: every register that changed is struck 2 f after the one above it, in pwndbg's order, the fill in over 6 f, no arm and no pulse (a dozen pulses at once are a flash, and a dozen arms a crowd); memory: the stack's window scrolls or fades to its new place, and the [backtrace](#backtrace)'s frames leave, slide and arrive; the idea; hold 36 f after the last strike; `advance`, the source and disassembly fading through if far; rest. Its marks are only on what was on screen to change. **A call stepped over** is a continue over one call, its result first: rax armed and struck as a walked register's, the call's annotation taking its C form and result with it, then the others in the wave ([chart](motion.md#a-call-stepped-over)) |
| `run` | steps that need not be read | over a graph, the mark goes from block to block in 8 f, round the rings, each edge taken flashes to gold and cools in 8 f, counts change in place; at a sprint (on the map) the gold moves only when the block changes, 4 f at most each, the trail's three edges following and the loops' counts ticking at their centres, and the picture settles at the phrase's end. Elsewhere: 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; no strikes, no held corners and no arcs drawing: a value changes in place under an 8 f crossfade, unmarked, and what the run changed is shown settled when it ends (its arcs fade in, 8 f, standing; no corners); no ties but the thread. A caption never names what a run veils. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most. A run longer than a phrase may `surface` and play on the map |
| `sprint` | steps to be got through | 4 f a step. The drawing grows and the clock sweeps; the source and the band's view are veiled as well; the mark and the pins move only at a phrase's end. Each change of pace ramps at 0.6 of the step before. A sprint plays on the map: `surface` before it, `dive` after it, at the stop it reaches; the windows glide with the pc, the marks flash and fade |
| `establish` | a scene's opening | done by 54 f: the panels fade in, 18 f each, 6 f apart (registers, stack, source, disassembly, the band's view, the drawing's panel: 0 to 48); from 30 f the drawing's elements fade in rising 8 units, 12 f each, 2 f apart in address order and all begun by 42 f, each with its row's quiet bracket (an `echo`: no lines). The first caption arrives at 60 f |
@@ -2325,7 +2378,9 @@ recording of `mock/heap.c`; `mock/intro.py` draws the introduction and
its blocks (29 to 37) from the same list recording and its mappings;
`mock/gen.py` draws 1 to 8; `mock/touch.py` draws the disassembly tied to the
stack (44 to 48) and the carry (56) from a fresh recording of `reverse` and its call; `mock/column.py`
-the column (49 to 55) from a fresh recording of `hello`. Each working
+the column (49 to 55) from a fresh recording of `hello`; `mock/regs.py` the introduction's chapter on
+registers (58 to 61) and its seam from chapter I (62) from a fresh recording of the introduction's program
+from line 40. Each working
frame has a `-480.png` beside it; the map has its 1080p (`19-map-1080.png`).
```sh
@@ -2348,6 +2403,7 @@ resvg -w 1920 19-map.svg 19-map-1080.png
python3 -B gen.py # 1 to 8, then resvg the same way
python3 -B touch.py # 44 to 48, 56 and 57 (it runs resvg and composes its sheets itself)
python3 -B column.py # 49 to 55 (the same)
+python3 -B regs.py # 58 to 62 (the same)
```
| Mock | Is | Blocks it shows |
@@ -2362,6 +2418,11 @@ python3 -B column.py # 49 to 55 (the same)
| [48](mock/48-tied-ways.png) | the sheet: three ways to say the row and its word are one thing, on 44's instant | A, names and the echo alone, pwndbg's offsets; B (recommended, `tied`), names, offsets from the frame's base and the touch; C, the name in the operand as IDA writes it, the row saying only what moved |
| [56](mock/56-carry.png) | `carry = .arrow` with `tied`, six instants numbered in their order: the load `mov rcx, [rbp - 8]`, then the store `mov [rbp - 0x18], rax` | the load: 1 the touch and `prev` read, rcx untouched; 2 the touch withdrawn as the carry climbs the gutter's right lane to rcx, its open chevron landing, rcx armed; 3 rcx struck, the carry gone, rcx's link to its pin. The store: 4 rax framed read, memory unmoved; 5 the carry down to `next`'s word, armed on its landing; 6 struck |
| [57](mock/57-aim.png) | `aim = .step` on `call reverse`, the instant after the return address is struck (46's third instant) | the touch drawn back as the aim leaves the word: from the return address up the gutter's left lane onto the disassembly's right rule at `401272`, the row after the call, its address framed in code's ink; rsp's pin not yet moved |
+| [58](mock/58-regs-pins.png) | the introduction's II3, held: rsp and rbp point into the stack | the `registers` built, every register a row, chrome and legend last; `segments` live: rip's row pin on list's code row (`◂ rip`, II2's, standing), rbp's and rsp's `under` pin in the stack's band, the band and its row framed with their values (`ink`'s echo); the 128 bytes on the shelf over the address space; the clock and its label, `II registers` |
+| [59](mock/59-regs-parts.png) | II5, struck: `mov edi, 0x10` | `reg`'s `parts`: rdi's eight bytes, the zeros in front at `pad`, `edi` `di` `dil` bracketed under the low ones; the operand `edi`, the part and its four bytes framed together; the one byte that changed struck, and the row's annotation with it; push's rows with no panel yet, the pc's; two texts beside on the left, the older dimmed |
+| [60](mock/60-regs-call.png) | II6, mid-step: `call malloc@plt` stepped over | rax struck with the result and the call's annotation with it, `malloc(16) = 405050`; rcx, rsi, rdi struck in the wave; r11's later hop held; PF and ZF set, held; the mark not yet moved; three texts beside |
+| [61](mock/61-regs-fold.png) | II8, the chapter's last picture | `fold` done: six rows, ten registers three to a row under a rule, rip; the corners of II6 and II7; the 128 bytes back from the shelf at the rows III's stack gives them, with I's three chains; reverse's rows, the pc on `push rbp`; the clock at 182 of 193 |
+| [62](mock/62-seam.png) | the seam from I to II, four instants at half size | `title`: I's last picture read; the title said, the label changed; the 128 bytes folding to the shelf along its height; II1's text landed and the registers' first rows arriving |
| [49](mock/49-column-call.png) | the column: `open`'s call (`hello`, moments 37 to 38), mid-step | the `shelf` (the log, its bytes, the registers with rsp struck on their tag); source 3, main's window, a stack of nineteen words; the touch down the gutter onto the stack's right rule; the newest bubble on its paper, level with the call row, the older one dimmed above it |
| [50](mock/50-column-stub.png) | the stub's `jmp` (38), the rest before its step | the descent in the column with the stack kept under it, the return address held on its top; the bubble's stem across the gutter to the jmp row |
| [51](mock/51-column-args.png) | libc's `open`, its last three walked (61 to 64), mid-step of `mov eax, 0x101` | the registers unfolded under the descent, rip's row above 888; the bubble level with the first of the three |
@@ -2454,6 +2515,10 @@ the band.
a run over the veil and at a sprint on the map; a climb longer than the window (`unroll`); the follow's
one move under a climbing pin (47's sixth instant shows where it ends, not the move); a carry to a folded
register or off a window (a stub); `carry = .value`.
+- The introduction's chapter II from its first beat to its last: II1's rows arriving, II2's `◂ rip` coming
+ in, II4's echo, II7's continue; `unpack` and `pack` and `fold` in motion (charts only); `parts` on rax
+ (`eax` `ax` `al`) and a write that zeroes a part's high bytes; the seams before III and IV and the video's
+ first title; the label alone in chapter I.
- The column: a fold and an unfold between beats (charts only); a beat `above`; a loop's bubbles stacking;
the scene's opening `below` and its relayout into the column; the column at a run; the floor holding a
window's continuation under a narrated pane (49 and 53 have the stack's there).
@@ -2597,7 +2662,22 @@ is not checked here. The tokens are under [Token changes](#token-changes).
order). The verbs `regroup` (walked, and at a run), `ink`, `enlarge`,
`column`, `frame up`, `decode`, `align` (also between the two forms of
`aligned`). A hexdump with no ink (the first picture only), and a word
- field ranged right, eight pairs wide.
+ field ranged right, eight pairs wide. **The introduction as one scene**
+ (motion.md's storyboard): the three scenes and a fourth, the registers,
+ joined into one (`intro`), its chapters in the order I, II registers,
+ III the stack, IV code; a `chapter`'s title said at its seam (`title`) and
+ kept as the clock's label; one clock over one recording, from its first
+ stop and only forward, on from II2; the registers built with every
+ register a row and folded on a beat (`fold`, the dive's fold as a verb of
+ its own); `reg`'s `parts` with `unpack` and `pack`; a call stepped over
+ (its result struck first, then the wave); `segments`' live pins each on
+ its beat with `ink`'s echo; the dump folded to the shelf while the
+ working frame stands (I4's shelf, lent) and unfolded at the stack's rows;
+ code rows with no panel round them until a later `frame up`; the
+ registers' one set across the chapters (11 rows), so that III's stack is
+ 356 to 868 and its program column main's rows 604 to 700 over reverse's
+ six, 712 to 888 (the three videos' II had eight rows of registers and
+ seven of reverse).
10. **Still from before**: the calls tree's small size and folds,
`metric.span.name_max` 300, `time.caption_max` 12 s and
`time.first_step` 4 s (5 s when a scene opens on the map), `time.dive`
@@ -2745,7 +2825,27 @@ is not checked here. The tokens are under [Token changes](#token-changes).
instructions in the window (or the binary, for the renderer to read
them); and a recording of the program by instruction from `main` to the
stop, so that a real `push`, a real `call` and the moment rsp moves are
- shown, not described.
+ shown, not described. **Its chapter on registers** needs the recording
+ to start earlier and to be the program's alone. From `list.c:40`,
+ main's `push(9)` (in place of `:41`, its `reverse()`), to `list.c:22` as
+ now: so that push(9) at line 11 is in it, its `mov edi, 0x10` and
+ `call malloc@plt`, a call that takes an argument and gives a result (push
+ is `void`, reverse takes nothing: malloc is the one real call with both
+ before reverse), and every instruction of malloc by instruction (162 in
+ this round's run), which the chapter steps over and the clock counts.
+ Chapters I, III and IV are found by name as now (`reverse`'s first
+ moment, the load on line 21) and do not move. Without the agent's
+ preload: its malloc wrapper leaves its own values in rsi, rdi and r8 to
+ r11 (the present recording's rdi at reverse's entry, `7ffff5c011e8`, lies
+ in no mapping a run without the agent has; that run's is 4), so the step over the call would strike eight registers,
+ four of them the tracer's and not the program's, where glibc's malloc
+ alone changes rax, rcx, rsi and rdi (and r11's word); IV's nodes then
+ take their chunks from `--heap` (glibc's heap at each stop) rather than
+ the agent's allocations. Every register at each stop as now; the stack's
+ 1024 bytes as now (the 128 bytes are the same words at reverse's entry);
+ the clock's count from the first stop at line 40 (the start-up's system
+ call stops before it are not the program's steps). Each register's
+ parts' names are the renderer's own table (`reg`'s `parts`).
- **For the graph**, per function and once: its blocks (first and last
address, how each ends: a conditional jump, a jump, an indirect jump, a
return, a call that does not return, or a fall into the next), each
@@ -2808,6 +2908,11 @@ and `metric.bytes` and `metric.slot`'s new columns are in, as asked.
| `metric.bubble` | none | Go 40 on 54, code mono 35; 40 characters and three lines at most (80 and two `above` a subject across both columns); padding 16, 812 wide at most; the newest on `raised`, older ones `dim` and bare; three at most; 12 between bubbles; the stem 2 in `dim`, a head 7 by 8 |
| `time.bubble` | none | in 0.30 rising 8 (`enter`), out 0.20; dim 0.30; out of the newest's way 0.40 (`glide`); the stem 0.20 in with the bubble, 0.20 back with the fire; between beats: fold 0.20 then 0.40 (the panel closing as its tag travels to the shelf), the stayers 0.40, unfold 0.40 (the tag back as the panel opens) then 0.20 |
| `metric.aligned` | `interleaved` only | `columns`: the seam 48 after the longest line in the window; each column's place ranged right 132 into it, its text 24 after; a line's first row `raised` |
+| `metric.parts` | none | the row's eight bytes from 72 on a pitch of 30, high first, `pad` at 45%; a part's row under it, widest first: a 2-unit `dim` bracket under its bytes, 3 out from the first and last, serifs 11 up; its name ranged right 10 before the bracket, mono 20 `dim`; three rows (four with `ah`) |
+| `time.unpack`, `time.pack` | none | `unpack`: the rows make room 0.30 (`glide`), the bytes spread 0.20, the parts 0.20 each, 0.10 apart; `pack`: the parts out 0.20, then the bytes close and the rows close up 0.40 (`glide`) |
+| `time.fold` | inside the dive's move | 0.60 (`glide`), the chains past the first hop out over its first 0.40, then the rule 0.20 |
+| `time.call_over` | none | the arguments read 0.10 apart from 0.30; still 0.20; rax armed 0.20 and struck at 0.80; the annotation's result 0.10; the wave from 1.10, 0.033 apart; hold 0.60; the step 2.4 with a wave of three |
+| `time.title`, `metric.chapter` | none | from the frame the last text is read: still 0.50; the texts out 0.20; the title in 0.30 at 0.80, rising 8; still 1.00; the opening from 2.10; the title out at its reading time or the opening's end; Go Medium 40, the numeral `faint`, the name `bright`; the label Go 18 `faint`, 24 left of the clock's count, crossfading 0.20 |
Unchanged and already there: the 1920 stage (its splits change, above), each pane's `strip`, the palette
with the marks of the last round (`wash`, `struck` `b54f42`, the corner),