summaryrefslogtreecommitdiff
path: root/anim/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'anim/README.md')
-rw-r--r--anim/README.md125
1 files changed, 75 insertions, 50 deletions
diff --git a/anim/README.md b/anim/README.md
index 5801c74..bf2100a 100644
--- a/anim/README.md
+++ b/anim/README.md
@@ -75,7 +75,12 @@ projection from its return address does, 36 f after); the writes of one step str
mark advances last; a rest. `walk` plays steps in full, `hurry` ramps the
pace down and up again (each step 0.6 of the one before) to a run (0.30 s a
step) or a sprint, `step` takes an explicit `Plan` (`Array.swap`,
-`syscalls.step`). Components read it through `Cursor.now(at)`.
+`syscalls.step`), and `continue` goes to a stop far from this one (a
+breakpoint): the line it leaves fires, the registers it changed strike in
+a wave 2 f apart in pwndbg's order (fill 6 f, no arm, no pulse), then
+memory and the idea, a 36 f hold, the mark out and in (6 f each, the
+source fading through first if far), a 24 f rest. Components read it
+through `Cursor.now(at)`.
## The scenes
@@ -87,7 +92,7 @@ step) or a sprint, `step` takes an explicit `Plan` (`Array.swap`,
| `sort` | insertion sort: compares and swaps | `subject`, `array` | `sort` |
| `syscalls` | open, read, close, write: the kernel's side | `subject`, `syscalls` | `hello` |
| `zoom` | one line of C as its instructions, the call's bytes | `none`, the camera at x2 | `steps` |
-| `sqlite` | a row's way to disk in SQLite: from `sqlite3_step` to `sqlite3BtreeInsert` (three continues, the row's struct on the stack), the commit's `unixWrite` nine calls under `main`, `pwrite64` of page 2 into the kernel, and the page read as a B-tree leaf | `subject` with the backtrace in the drawing's place, then `syscalls`; its view a `hexdump.Dump` | `sqlite` |
+| `sqlite` | a row's way to disk in SQLite: from `sqlite3_step` to `sqlite3BtreeInsert` (three continues, the row's struct on the stack), the commit's `unixWrite` nine calls under `main`, `pwrite64` of page 2 into the kernel, and the page read as a B-tree leaf | `subject`, `backtrace` (`Context.Options.backtrace`), then `syscalls`; its view a `hexdump.Dump` | `sqlite` |
| `gallery` | every block in its states | all three | `gallery` |
## The blocks
@@ -97,20 +102,20 @@ every state the code has in the `gallery` scene.
| Layer | Block | Where | Notes |
| --- | --- | --- | --- |
-| 0 tokens | grid, colour, type, the splits | `src/theme.zig` | per "Token changes"; JetBrains Mono NL (`.code*` faces) for all mono, Medium under 30 |
+| 0 tokens | grid, colour, type, the splits | `src/theme.zig` | per "Token changes" (`metric.calls`, `time.pin`, `time.continue_wave`, `time.relayout_fade` there; the insn's character counts gone); JetBrains Mono NL (`.code*` faces) for all mono, Medium under 30 |
| 1 atom | `address` (`lead`, `name`, `rwx`), `value` (and `Ui.typed`: `fd`, `bool`, `char`), `arrow` (`points`, `holds`, `more`), `mark`s, `plaque` (`chip`), `pin` (`row`, `under`), `bracket` (`quiet`, `tie`, `thread`), `tag` | `src/ui.zig` (`Ui.address`, `.value`, `.arrow`, `.written`, `.read`, `.cellWritten`, `.cellRead`, `.current`, `.trail`, `.unknown`, `.chip`, `.pinRow`, `.pinUnder`, `.bracket`, `.panel`) | marks in the context: `armed`, `struck`, `held` (a tick), `read`; in a lens's cell the same with a bar |
-| | `byte` | `src/rows.zig` `bytes` | `number`, `pointer`, `text` (a string's ink), `allocator` (also bytes that are no field of what a dump is about), `unread`; `pad`; `bytesAt` moves the bytes right of a long (stack) address |
+| | `byte` | `src/rows.zig` `bytes` | `number`, `pointer`, `text` (a string's ink), `loose` (a byte of no field: the allocator's, padding, past what a dump is of), `unread`; `pad`; `bytesAt` moves the bytes right of a long (stack) address, by the dump's widest |
| 2 row | `chain`, `reg` (and `rip` with the flags), `slot`, `line`, `bytes`, `call` (`span`, `callRow`) | `src/rows.zig` | `chain` follows `zt.telescope.chase`; cut at its far end, `more` |
| | `insn` | `src/disasm.zig` | columns at 2, 31, 40, 134, 180, 264, 564; operands whole, the annotation from 564 or a character after them; then a size word goes, then the operands give way, never inside `[]`; `current`, `ran` (every instruction of the last three steps), `ahead`, `outside`; the jump lane from the jump just before the pc's moment |
-| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the stack's window on `[rsp, rbp+16)` keeping the touched word in view, rsp and rbp's pins travelling (keeping their place among the names they leave and join); a window that moves more than 16 words fades out and in round memory's strike; a frame's name longer than the spans' room shortens the chains beside it; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames`, the frames two stops share sliding to their new depth |
-| | `source` | `src/source.zig` | the whole file in a window, its middle third; numbers as wide as the window needs (SQLite's have five digits), the text moved right by as much; a window more than two windows away fades out and in |
-| | `disasm` | `src/disasm.zig` | 17 rows (9 as subject), fewer above near a function's start |
-| | `hexdump` | `src/hexdump.zig` | a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; `Dump`, a view of a region by the fields a scene gives it (`Field`: where, how long, read as a number, big-endian or not, a pointer, text, or left to the eye), the rows that hold a field and a `more` row for those left out, marks the scene plays, the bytes a syscall was given as the kernel took them, and only what the debugger read at the stop (`seen`) |
-| | lenses: `nodes`, `array`, `calls`, `syscalls` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`) | the drawing in `band` (over the program column), its view in `view` (over the state column): `nodes` and `array` a dump (`hexdump.panel`), `calls` the backtrace with arguments, `syscalls` the bytes the call is given or fills |
+| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the stack's window on `[rsp, rbp+16)` keeping the touched word in view, its tag the first and last word shown (`rsp+20 to rsp+48`), rsp and rbp's pins travelling 18 f after rsp's strike (`time.pin`, keeping their place among the names they leave and join), at rest only where the register points; a window that moves farther than its own height (six or eight slots) fades out and in round memory's strike, and what it brings, and what changed before it, is plain; a frame's name longer than the spans' room shortens the chains beside it; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames`, the frames two stops share sliding to their new depth; the backtrace as a lens's drawing with `Context.Options.backtrace` |
+| | `source` | `src/source.zig` | the whole file in a window, its middle third; numbers as wide as the program's largest line (SQLite's six digits), the text moved right by as much; a window going farther than its own height fades out and in |
+| | `disasm` | `src/disasm.zig` | 17 rows (9 as subject), fewer above near a function's start; the line column as wide as the source's; two windows that overlap scroll, others fade out and in |
+| | `hexdump` | `src/hexdump.zig` | a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; one reading for every dump (`hexdump.reading`), a list a character apart, a typed number as its type reads (`char` quoted, `bool` by name); the address room once a dump, by its widest; `Dump`, a view of a region by the fields a scene gives it (`Field`: where, how long, read as a number, big-endian or not, a pointer, text, or left to the eye), the rows that hold a field and a `more` row for each stretch left out, and where those rows outnumber the window, a window kept round the first row a mark or the step is on, the rest folded into `more` rows; marks the scene plays, and the step's only from the stop it came in at (`since`); the bytes a syscall was given as the kernel took them (`given`), and only what the debugger read at the stop (`seen`) |
+| | lenses: `nodes`, `array`, `calls`, `syscalls`, `backtrace` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`), `src/context.zig` (`Backtrace`, `lens`) | the drawing in `band` (over the program column), its view in `view` (over the state column): `nodes` and `array` a dump (`hexdump.panel`), `calls` the backtrace with arguments, `syscalls` the bytes the call is given or fills, `backtrace` (eleven rows as subject, five beside) a `Dump` the scene gives; an `under` pin's names in the order they came, the first left |
| 4 tie | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, draws in the channels: a link climbs to a node by the gutter's left lane and goes down to a slot by the right, its name riding its head, a target past the stack's window a stub and a row count; a projection from the view's bytes, or from a frame's return address to its call's node |
| 5 frame | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject` (`theme.layout.split`): the band is `band` (the drawing) and `view`; `relayout` fades the drawing round its move; `holdStack` holds the stack's window for the camera, with `free` slots |
| | `clock`, `caption`, `veil`, `card` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the clock still while a step plays, its piece fading in once the mark lands; a caption stays its reading time; the title card is `scenes/title.zig` |
-| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `travel` (pins), `advance`, `cascade`, `run`, `sprint`, `establish` (`Context.establish`: a drawing's elements fade in rising, no lines), `scroll`, `relayout`, `visit`, `say` | `src/cursor.zig` (the timetable), the blocks (each draws its state at the instant) | tokens in `theme.time`; a level gives up its slot when nothing it touched is drawn (`Recording.drawn`) |
+| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `travel` (pins), `advance`, `cascade`, `continue` (`Cursor.continue`, `Plan.wave`), `run`, `sprint`, `establish` (`Context.establish`: a drawing's elements fade in rising, no lines), `scroll`, `relayout`, `visit`, `say` | `src/cursor.zig` (the timetable), the blocks (each draws its state at the instant) | tokens in `theme.time`; a level gives up its slot when nothing it touched is drawn (`Recording.drawn`) |
`Recording` (`src/Recording.zig`) is the index every block reads: lines,
calls, syscalls, allocations, which registers and bytes each moment changed
@@ -141,8 +146,8 @@ and no canary stepped through that the source does not say.
A recording that begins inside a call (`--from`) has that call open from
its first stop (`Recording.index`, from the frame chain). Writes are the
bytes whose value changed, to the element the instruction stored (its
-`touch`); a store of the same value is kept apart (`store_spans`) and
-counts as assigning a local. A register's change over a step is net: a
+`touch`); a store of the same value is kept apart (`storedSame`) and
+counts as assigning a local (and as a name coming to a node's pin). A register's change over a step is net: a
call's rsp put back is not struck. The vDSO's `clock_gettime` is stepped
through under the runtime and the agent: its retry loop makes the counts
vary a little from one recording to the next. An address no symbol
@@ -153,59 +158,80 @@ holds is named from its module's first mapping (`list+2c89`).
`tools/chart.py chart` on the 1080p exports in `out/` (the designer's five
checks; its regions follow the two-panel band now). Encoded with `-g 600`:
x264's keyframe at 10, 20, 30 s is a one-frame fade the instrument sees.
+"Before" is the exports this pass started from (10 November, evening);
+"after" the ones it made: the continue's wave, plain windows and dumps
+after a fade, the crossing's order, pins at rest only where their
+register points, `time.pin`, the compact reading, names by arrival.
| | fib | list | sort | syscalls | zoom | sqlite |
| --- | --- | --- | --- | --- | --- | --- |
-| POP, round 2 / 3 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 |
-| CROWD, round 2 / 3 | 7 / 2 | 2 / 7 | 10 / 6 | 5 / 1 | 4 / 3 | – / 1 |
-| RUSH, round 2 / 3 | 0 / 0 | 0 / 2 | 2 / 0 | 1 / 2 | 0 / 0 | – / 1 |
-| AIR, round 3 | 0 | 0 | 0 | 0 | 1 | 4 |
-| seconds, round 3 | 41.5 | 60.5 | 42.0 | 38.5 | 32.0 | 64.6 |
-
-(sort as the coordinator re-exported it without the camera; syscalls and
-sqlite after the crossing's changes: a register carries a call only while
-it holds the argument at the stop shown, `rax` is struck after the
-kernel's `returns` row; fib, list and zoom are the round-3 exports, made
-before the stack's and backtrace's motions below.)
+| POP, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 |
+| CROWD, before / after | 2 / 2 | 7 / 7 | 5 / 5 | 1 / 1 | 4 / 4 | 1 / 0 |
+| RUSH, before / after | 0 / 0 | 2 / 2 | 0 / 0 | 2 / 1 | 0 / 0 | 1 / 1 |
+| AIR, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 1 / 1 | 4 / 5 |
+| seconds, after | 41.5 | 60.5 | 42.0 | 37.9 | 32.0 | 64.6 |
What fires, and why it is left:
-- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 17.58 are the
+- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 17.60 are the
veil coming over the registers, stack and disassembly at the first
shortened step (one veil over three panels); zoom 9.65 and 21.55 the
camera (the regions are fixed on the screen); zoom 11.75 the stack's
window scrolling to its hold under the camera (the stack fills every
- region there). The rest (list 15.92, 19.32 and the others like them,
- sort 11.68, 27.12, 29.42 and the others, syscalls 35.35, sqlite 43.40)
- are an `advance`: the thread, the plaques and rip move as one mark, the
+ region there); sort 30.00 is x264's keyframe on a step's first frame.
+ The rest (list 15.92, 19.32 and the others like them, sort 11.68,
+ 29.42 and 36.13, syscalls 34.75, zoom 3.62) are an
+ `advance`: the thread, the plaques and rip move as one mark, the
source and the disassembly scroll with it, and a link or projection
- goes back into its pin, all on the catalogue's one frame.
-- RUSH: list 29.20 and 29.55, syscalls 29.37 and 29.72, sqlite 9.10: a
- caption arrives, and the next change the instrument sees is the
- keyframe at 30.00 (10.00) (a fade of every region over one frame,
- 0.00% at its peak).
+ goes back into its pin, all on the catalogue's one frame. (sqlite's,
+ the crossing's advance at 43.40, no longer starts with another panel.)
+- RUSH: list 29.20 and 29.55, syscalls 29.32, sqlite 9.10: a caption
+ arrives, and the next change the instrument sees is the keyframe at
+ 30.00 (10.00) (a fade of every region over one frame, 0.00% at its
+ peak).
- AIR: a caption's reading time on a still picture: the last one's and
- the 2 s on the finished picture (zoom 26.88, 3.1 s; sqlite 60.02,
- 4.6 s), and in sqlite three more, each a dense caption over a stop
- (11.38, 7.2 s: the arguments; 32.72, 3.5 s: the commit's backtrace;
- 50.03, 4.9 s: the page's header), its fields framed as it names them.
+ the 2 s on the finished picture (zoom 26.88, 3.1 s; sqlite 60.03,
+ 4.6 s), and in sqlite four more, each a dense caption over a stop
+ (11.38, 7.2 s: the arguments; 24.57, 3.2 s: the two more rows, now
+ that a continue is a wave and a 36 f hold and not a cascade's longest
+ hold; 32.95, 3.2 s: the commit's backtrace; 50.03, 4.9 s: the page's
+ header), its fields framed as it names them.
## What is not done
- Back pointers between nodes still run under the nodes: a page keyline
round each pin's stub and head shows them passing behind it (there is
no lane for them in `beside`).
-- Names keep their side when one of two leaves a pin and when a pin's
- name travels; a name that arrives where another already is takes the
- right, and once it has landed the pin's own order (variables, then
- registers) may put it on the other side. (In the stack's lane, rsp or
- rbp travelling alone keeps its place among the names it leaves and
- joins; both travelling to rows with other names is not handled.)
-- The hexdump's reading of a `char` or `bool` field (the lens's values
- and cells read them by type; the dump's reading column does not).
+- An `under` pin's names are in the order they came to the node (the
+ recording read back from the stop shown), so a name that lands where
+ another is stays on the right it travelled on; but one left alone
+ where it was on the right keeps that side only for the step in which
+ the other left, and takes the left at the next. A third name coming to
+ a pin whose two sides are taken is counted (`+1`), unless it is a
+ variable the scene names and a register holds the right, which it then
+ takes; on its way it is drawn over the right-hand name (list, 7.5 s).
+ A pin's count (`+1`) can run into the left-hand name of the next
+ node's pin (list, 26 to 57 s).
+ (In the stack's lane,
+ rsp or rbp travelling alone keeps its place among the names it leaves
+ and joins; both travelling to rows with other names is not handled.)
+- Pins travel with `time.pin`'s times, but on `standard`, not the
+ catalogue's `glide`, in the stack's lane and the array; a pin in a
+ drawing sets off when the idea strikes (the projection's arrival),
+ not 18 f after its word's strike.
+- The disassembly scrolls or fades over the mark's advance: 24 f where
+ the source's window moves too, 12 f where the mark only jumps.
+- Whether the stack's window faded at a step is judged by the slots it
+ shows now: after a relayout to fewer, a step that scrolled may lose
+ its ticks.
+- A frame's name on a `call` span is never cut (`metric.span.name_max`,
+ 300 units, is not built); the calls tree's small and folded sizes are
+ not built.
- A link to a slot past the stack's window ends in its stub and row count:
drawn in the sqlite scene only (rsi to the struct on the caller's
- stack, `23 rows`, 4.2 s).
+ stack, `23 rows`, 5.0 s; in a continue a link sets off with memory's
+ strike, when the window is at its new place). One to a slot above the
+ window would put its count over the panel's tag.
- The calls tree's leaf spacing holds for fib(5); past about ten leaves
nodes and badges collide (the catalogue's known case).
- `heap` and `pages` lenses are not in the band (`Timeline` is the old
@@ -222,11 +248,10 @@ What fires, and why it is left:
- A program's frame arguments are in the backtrace only for calls the
recording tells (an instrumented program's); at a breakpoint the
callee's are in its registers, which the scene's captions name.
-- The sqlite scene changes what is over the band (the backtrace, then the
- kernel's side) and its view (the SQL at rbx, the row, the page) by a
- fade, not by a verb of the catalogue; the backtrace in the band's
- drawing is a split the catalogue does not have (`subject` with the
- backtrace where the drawing goes: eleven rows).
+- The sqlite scene changes what is over the band (the backtrace lens,
+ then the kernel's side) and its view (the SQL at rbx, the row, the
+ page) by fades scripted in the scene (12 f out, then 12 f in); the
+ kernel's side does not bring its elements in as at `establish`.
- `zig build test` prints "failed command" for each scripted scene: that
is the run echoing its stderr (the Vulkan headless warning), not a
failure; the summary line is the verdict.