summaryrefslogtreecommitdiff
path: root/anim/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'anim/README.md')
-rw-r--r--anim/README.md136
1 files changed, 80 insertions, 56 deletions
diff --git a/anim/README.md b/anim/README.md
index 74596bb..57beeb5 100644
--- a/anim/README.md
+++ b/anim/README.md
@@ -63,9 +63,10 @@ a later one (`Recording.Stop`: `.moment`, `.line`, `.over`, `.call`,
`.syscall`). For each step it writes a timetable, a `Plan`: the cascade.
The line fires (12 f); each level the step touched strikes 18 f after the one
before, in the order CPU, memory, idea (a level the scene does not show, or
-the step did not touch, gives up its slot; a drawing made of bytes strikes
-when the projection from them arrives, 24 f after them, and its write 12 f
-later still); the writes of one step strike 6 f apart; a hold to read; the
+the step did not touch, or touched nothing drawn, gives up its slot; a
+drawing made of bytes strikes when the projection from them arrives, 24 f
+after them, and its write 12 f later still; a call's node when the
+projection from its return address does, 36 f after); the writes of one step strike 6 f apart; a hold to read; the
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`,
@@ -79,19 +80,19 @@ 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 |
-| 1 atom | `address` (`lead`, `name`, `rwx`), `value`, `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`, `.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`, `allocator`, `unread`; `pad` |
| 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; `current`, `ran`, `ahead`, `outside`; the annotation from the moment's `touch` and `branch` |
-| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | the stack's `call` spans and the backtrace from `zt.telescope.frames` |
+| | `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; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames` |
| | `source` | `src/source.zig` | the whole file in a window, its middle third |
-| | `disasm` | `src/disasm.zig` | 17 rows (11 as subject), fewer above near a function's start |
-| | `hexdump` | `src/hexdump.zig` | a lens's right half: `bytes` rows and their reading |
-| | lenses: `nodes`, `array`, `calls`, `syscalls` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`) | in the band; `nodes` and `array` with their dump |
-| 4 tie | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, draws in the channels |
-| 5 frame | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject` (`theme.layout.split`) |
-| | `clock`, `caption`, `veil`, `card` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the title card is `scenes/title.zig` |
-| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `advance`, `cascade`, `run`, `sprint`, `establish`, `scroll`, `relayout`, `visit`, `say` | `src/cursor.zig` (the timetable), the blocks (each draws its state at the instant) | tokens in `theme.time` |
+| | `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 |
+| | 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 |
+| 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`) |
`Recording` (`src/Recording.zig`) is the index every block reads: lines,
calls, syscalls, allocations, which registers and bytes each moment changed
@@ -104,58 +105,81 @@ and read (a debugger's `touch` reads count), each moment's `touch` and
debugger: registers, the stack, what they point at, the instructions round
the pc with their lines and callees' parameter counts, at every stop), each
by a bare name in a directory of its own with an empty environment, without
-address randomisation. The instrumented ones are built `-no-pie`, so their
-code and heap have short addresses as the design's columns expect.
+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
+the clock's retry loops it steps through). The instrumented ones are built
+`-no-pie -fno-stack-protector -Wl,-z,now`: short addresses, no resolver
+and no canary stepped through that the source does not say.
-| Name | Program | Stops | Also |
-| --- | --- | --- | --- |
-| `steps` | `fib.c`, static musl, `-O0` | every instruction | |
-| `hello` | `hello.c`, static musl | every line | reads `tools/note` |
-| `sort` | `sort.c` built by `ztrace cc` (`calls,vars,stores,loads`) | every line | `--ring` |
-| `list` | `list.c` built by `ztrace cc` (`calls,vars,stores,loads`) | every line | `--alloc --preload` the agent: allocator headers are read |
-| `gallery` | a copy of `list`, kept in `test/gallery/list.ztrace` | | the gallery's pictures depend on the drawing only |
+| 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 |
+| `gallery` | the old `list` by line, kept in `test/gallery/list.ztrace` | | 134, 88 KB | the gallery's pictures depend on the drawing only |
+
+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
+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
+holds is named from its module's first mapping (`list+2c89`).
## Motion, as measured
-`tools/chart.py chart` on the 1080p exports (the designer's five checks; the
-baseline is `design/motion.md`'s table, measured before the frame changed):
+`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.
| | fib | list | sort | syscalls | zoom |
| --- | --- | --- | --- | --- | --- |
-| POP, before / now | 68 / 0 | 40 / 0 | 35 / 0 | 0 / 0 | 1 / 0 |
-| CROWD, before / now | 75 / 7 | 43 / 2 | 44 / 10 | 4 / 5 | 5 / 4 |
-| METRONOME, before / now | 68 steps / none | 15 / none | 36 / none | 4 / none | none |
-| RUSH, now | 0 | 0 | 2 | 1 | 0 |
-| seconds | 40.6 | 59.3 | 39.5 | 34.8 | 30.2 |
+| POP, round 2 / 3 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 |
+| CROWD, round 2 / 3 | 7 / 2 | 2 / 7 | 10 / 5 | 5 / 1 | 4 / 3 |
+| RUSH, round 2 / 3 | 0 / 0 | 0 / 2 | 2 / 0 | 1 / 2 | 0 / 0 |
+| AIR, round 3 | 0 | 0 | 1 | 0 | 1 |
+| seconds, round 3 | 41.5 | 60.5 | 46.7 | 38.2 | 32.0 |
-What still fires, and why it is left:
+What fires, and why it is left:
-- CROWD at each `advance` that crosses a function (source, disassembly and
- rip move together: the catalogue's `advance` says they are one mark),
- inside `run` and `sprint` stretches (steps that are not to be read), and
- in fib at 22.25 s: a one-frame change in the disassembly and the stack on
- a step's first frame, beside the fire, not yet found.
-- AIR at each scene's opening: the designed stillness, 1 s and 0.5 s a panel.
-- RUSH in sort and syscalls at the last caption: the last step's cool and
- ticks still settle under it.
+- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 22.28 are the
+ veil coming over the registers, stack and disassembly at the first
+ shortened step (one veil over three panels); sort 9.60 and 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 31.82 and 34.12, syscalls 35.05) 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.17 and 29.52: a caption
+ arrives, and the next change the instrument sees is the keyframe at
+ 30.00 (a fade of every region over one frame, 0.00% at its peak).
+- AIR: the last caption's reading time and the 2 s on the finished
+ picture (sort 42.17, 4.6 s; zoom 26.88, 3.1 s).
## What is not done
-- The instrumented recordings (`list`, `sort`) clobber registers between
- lines, so their registers are `quiet` (no strikes, no links) and their
- pins name variables. A `--by insn` recording of `list` with only `vars`
- is 1.6 M moments (the loader and libc start-up): too many. So `link`, and
- `ran` rows with the jump lane, are seen in the scenes of `steps` (fib,
- zoom) only; a recording by line knows no instructions between its stops.
-- `establish` for a lens (its elements rising from their rows by
- projection) is not drawn: lenses fade in with the panels.
-- The `thread`'s brackets on the disassembly change runs at the middle of
- the advance; only the source's slides.
-- `value` classes `fd`, `flags` (other than rip's), `bool`, `char` are not drawn.
-- Back pointers between nodes run under the nodes and can cross a pin's stub.
-- `heap` and `pages` lenses are not in the band (`Timeline` is the old far view).
-- The camera rests at x2 in `zoom` (the stack of the `none` split fills it);
- x1.5 is supported (`theme.camera.scales`) but no scene uses it.
-- `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.
+- 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.
+- 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).
+- A link to a slot past the stack's window ends in its stub and row count
+ (`12 rows`); no scene's link has such a target, so it is drawn in no
+ export.
+- 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
+ far view).
+- SQLite (the next rung) is not started.
+- `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.