summaryrefslogtreecommitdiff
path: root/anim/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'anim/README.md')
-rw-r--r--anim/README.md86
1 files changed, 65 insertions, 21 deletions
diff --git a/anim/README.md b/anim/README.md
index bf2100a..c59630a 100644
--- a/anim/README.md
+++ b/anim/README.md
@@ -88,7 +88,7 @@ through `Cursor.now(at)`.
| --- | --- | --- | --- |
| `title` | the series and the legend of marks | a card | |
| `fib` | recursion: each call a frame and a node | `subject`, `calls` | `steps` |
-| `list` | a list reversed: each `next` turned | `subject`, `nodes` | `list` |
+| `list` | a list reversed: each `next` turned; it opens on the map and dives into the frame; after the first load the pointer loaded opens in a loupe, and the `next` in it one deeper | `subject`, `nodes` | `list` |
| `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` |
@@ -103,17 +103,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" (`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 |
+| 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`, `.corner`, `.read`, `.cellWritten`, `.cellRead`, `.current`, `.trail`, `.unknown`, `.chip`, `.pinRow`, `.pinUnder`, `.bracket`, `.panel`) | marks as mock 15's column B: `current` the white wash (`color.wash`) and the gold plaque; `struck` the softened paper (`color.struck`) with bold bright digits; `held` a turned corner (9; 12 on a lens's cell), in over the cool's last 6 f (`Heat.corner`, `time.strike.corner`); `armed`, `read` |
| | `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` |
+| 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`. `slot`: pins from 16, the offset from rsp ranged right to 172, the address at 184, the chain, its role ranged right where the room ends, from `zt.telescope.slots` (`saved rbx`, a local's name in primary, `argc`, `argv[0]`, `argv end`, `envp end`, `auxv`; nothing for a return address or `.none`). `bytes`: the bracket at 24, the address at 34, the bytes 12 after it and at 132 at least |
+| | `arc` | `src/rows.zig` (`Arcs`), `src/hexdump.zig` (`pointerArcs`) | a pointer to a row of its own panel: lanes at 4, 10, 16 in a dump or a loupe, 4 and 10 on the stack; longest outermost, a chain in one lane; standing at 60% toward the page, full in the step that writes or reads it and always in a loupe; rewritten: the old dashed with the arm, fading from 6 f after the strike as the new draws (12 f), quieting with the cool; a stub to the rule for a target in the region past the window, only in its step; a saved rbp's only in its step; a dump withholds the arcs an open loupe carries |
| | `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, 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`) |
+| | `loupe` | `src/loupe.zig` (`canim.loupe`, `Loupe.open`, `.close`) | five rows round a pointer's target, lifted (`color.lift`, `lift_tag`, `shade` 12 and 16; 20 and 26 deeper), hanging from its pointer (its tag on the row's foot, 92 left of the digits, clamped to the stage), a 4-high bracket under the digits its stem, the target's fields framed bright; from a register, or from a pointer field of a loupe; `open` 36 f (read 6, stem and rise 18 with the shadow, the frame 6 f after), `close` 12 f |
| | 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 |
+| 5 frame | `map`, `minimap`, `dive`, `surface` | `src/map.zig` (`Map`, `split`, `minimap`), `Context.map` | the working frame's panels bound to a stage of 3840 by 2160 (`map.split`: the drawing and the source, the disassembly 69, the view 32, the registers and the backtrace, the stack 69 from 16 words above rsp); its rows published while `ui.mapping`; the working windows outlined (2 `dim`, 4 out); the minimap the same at a twentieth under the clock (text as 1-unit strokes at 45% toward the page, marks as blocks; `ui.strokes`), the count ranged right at 1648; `Map.show`, `.dive` (outlines bright 6 f, veil to 24, each panel from its window to its place 60 f, 6 f apart in reading order, opaque on the way, its rows on the window's rows, its tag and rules in at the end; the map falls to the minimap's rect over 72 f; 120 f and 30 f still), `.surface` (the dive back, 84 f, then 30 f still); per-panel transforms through `context.at` (`context.zoomed`) |
+| | `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`, `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`) |
@@ -126,7 +129,9 @@ and read (a debugger's `touch` reads count), each moment's `touch` and
`build.zig` records four programs of `tools/` under `ztrace record` (the
debugger: registers, the stack, what they point at, the instructions round
-the pc with their lines and callees' parameter counts, at every stop), each
+the pc with their lines and callees' parameter counts, what each stack
+word is (`zt.telescope.slots`), at every stop: `--stack 1024 --around 256
+--disasm 69`, what the map needs, except where noted), each
by a bare name in a directory of its own with an empty environment, without
address randomisation, with the tools built `ReleaseFast` (a step through
the agent's or the runtime's code is a moment, and a slow tracer stretches
@@ -136,12 +141,12 @@ and no canary stepped through that the source does not say.
| Name | Program | Stops | Moments, bytes | Also |
| --- | --- | --- | --- | --- |
-| `steps` | `fib.c`, static musl, `-O0` | every instruction | 1999, 336 KB | |
-| `hello` | `hello.c`, static musl | every line | 233, 101 KB | reads `tools/note` |
-| `sort` | `sort.c`, `ztrace cc --instr vars --only sort,a` | every instruction, `--from main` | 5076, 617 KB | `--ring`: the variables' names and types; each `__zt_var` call is stepped (4 of them) |
-| `list` | `list.c`, `ztrace cc --instr vars --only push,reverse,head` | every instruction, `--from reverse` | 3421, 528 KB | `--alloc --preload` the agent: allocator headers are read; the pushes (the agent's and the runtime's first calls) run through |
+| `steps` | `fib.c`, static musl, `-O0` | every instruction | 1999, 431 KB (336 KB before) | |
+| `hello` | `hello.c`, static musl | every line | 233, 126 KB (101 KB) | reads `tools/note` |
+| `sort` | `sort.c`, `ztrace cc --instr vars --only sort,a` | every instruction, `--from main` | 5154, 799 KB (617 KB) | `--ring`: the variables' names and types; each `__zt_var` call is stepped (4 of them); `--stack 256` (below) |
+| `list` | `list.c`, `ztrace cc --instr vars --only push,reverse,head` | every instruction, `--from reverse` | 3369, 782 KB (528 KB) | `--alloc --preload` the agent: allocator headers are read; the pushes (the agent's and the runtime's first calls) run through; `--stack 256` (below) |
| `gallery` | the old `list` by line, kept in `test/gallery/list.ztrace` | | 134, 88 KB | the gallery's pictures depend on the drawing only |
-| `sqlite` | `sqlite.c` (three rows into a table, committed) with SQLite 3.50.4's amalgamation, system clang `-O2 -g -fno-omit-frame-pointer -no-pie -fno-stack-protector -Wl,-z,now`, glibc | `--by break`: `sqlite3_step`, `sqlite3BtreeInsert`, `unixWrite`, and the instruction after its `pwrite64` (found by objdump); every syscall recorded, `-s 4096`, `--stack 512` | 181 (42 stops, 138 syscalls), 95 KB | made only with `-Dsqlite=DIR` (default `~/05-genizah/sqlite/sqlite-amalgamation-3500400`), in a new temporary directory each time; `sqlite3.c` is embedded as the source |
+| `sqlite` | `sqlite.c` (three rows into a table, committed) with SQLite 3.50.4's amalgamation, system clang `-O2 -g -fno-omit-frame-pointer -no-pie -fno-stack-protector -Wl,-z,now`, glibc | `--by break`: `sqlite3_step`, `sqlite3BtreeInsert`, `unixWrite`, and the instruction after its `pwrite64` (found by objdump); every syscall recorded, `-s 4096` | 181 (42 stops, 138 syscalls), 233 KB (139 KB) | made only with `-Dsqlite=DIR` (default `~/05-genizah/sqlite/sqlite-amalgamation-3500400`), in a new temporary directory each time; `sqlite3.c` is embedded as the source |
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
@@ -150,26 +155,38 @@ bytes whose value changed, to the element the instruction stored (its
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
+vary a little from one recording to the next, and with a slower stop it
+seldom gets out: `list` with `--stack 512` took 27 000 to 42 000 moments,
+with 1024 0.3 to 1.6 million (100 MB, minutes), against 3 900 at 256
+(`--around` and `--disasm` matter little). So the two instrumented
+programs keep `--stack 256` (48 words with the 128 bytes under rsp): their
+map's stack column is shorter. The tracer should run through a call into
+the vDSO as `step` runs through code without lines. An address no symbol
holds is named from its module's first mapping (`list+2c89`).
## Motion, as measured
`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.
+checks; its regions are the working frame's; the minimap, 1664 to 1856 by
+912 to 1020, is in none). Encoded with `-g 600`: x264's keyframe at 10,
+20, 30 s is a one-frame fade the instrument sees. "Before" is the last
+pass's exports; "after" this pass's: the new marks, the stack's row, arcs,
+the minimap, the list's map and dive and its loupes, the recordings remade.
| | fib | list | sort | syscalls | zoom | sqlite |
| --- | --- | --- | --- | --- | --- | --- |
| 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 |
+| CROWD, before / after | 2 / 2 | 7 / 6 | 5 / 4 | 1 / 1 | 4 / 3 | 0 / 1 |
+| RUSH, before / after | 0 / 2 | 2 / 2 | 0 / 0 | 1 / 1 | 0 / 0 | 1 / 2 |
+| AIR, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 1 / 1 | 5 / 5 |
+| seconds, after | 41.5 | 70.9 | 42.0 | 37.9 | 32.0 | 64.6 |
+
+New this pass: list's CROWD at 2.52 is the dive (the windows go bright,
+then every panel sets off within 0.5 s: by design one move); fib's RUSH at
+5.78 and 7.30 is x264 noise in the caption band (30 pixels changing by 6
+to 24 levels under the still caption while the panels move), not a
+caption arriving; sqlite's new RUSH at 19.05 is not examined. The rest are
+as below.
What fires, and why it is left:
@@ -199,6 +216,33 @@ What fires, and why it is left:
## What is not done
+- The map is packed into fixed places (`map.split`): a panel longer than
+ its column is a window of what fits; continuing in the next column's
+ free space under `continued`, the key in a column's foot, `memory` in
+ a scene without a lens, and loupes as panels on the map (and as lifted
+ blocks on the minimap) are not built. The sqlite scene's lenses (the
+ backtrace, the kernel's side) and the zoom scene have no drawing on
+ their map. A disassembly of 69 rows shows what the recording decoded
+ round the pc, so a small function leaves rows empty.
+- The minimap draws no thread and no `flash`; its windows are outlined a
+ frame behind the panels that publish them after the clock (the lens's
+ view). The scene's focus is not set on it.
+- `dive`: every panel travels 60 f (the catalogue's 72 f is the map's
+ fall), so that seven of them 6 f apart land by 120 f; the drawing does
+ not crossfade between sizes (the list's are the same, subject on both);
+ panels draw in the scene's order (source, disassembly, registers, stack,
+ then the lens), not the reading order, so the stack passes over the
+ registers' lower rows, opaque, for about 0.35 s before it lands. Only
+ the list opens on the map; no scene surfaces, and no sprint or far
+ continue plays on the map.
+- A loupe keeps to the stage but does not yet move past the current marks
+ or a changed row; on the 1920 stage a deeper loupe has 20, not 120, to
+ its right (the stage's edge), and covers most of the first. The
+ catalogue's stem is 3 in its strokes and 4 in the loupe's anatomy: it is
+ 4 here.
+- An `arc`'s lane change does not glide (12 f): a lane is given each
+ frame from the arcs then present.
+
- 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`).