diff options
Diffstat (limited to 'anim/README.md')
| -rw-r--r-- | anim/README.md | 136 |
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. |
