diff options
Diffstat (limited to 'anim/README.md')
| -rw-r--r-- | anim/README.md | 109 |
1 files changed, 78 insertions, 31 deletions
diff --git a/anim/README.md b/anim/README.md index 57beeb5..5801c74 100644 --- a/anim/README.md +++ b/anim/README.md @@ -20,7 +20,12 @@ python3 tools/chart.py chart out/fib-1080.mp4 --out out/motion/fib # the desig ``` Needs what sketchbook and ztrace need, and `setarch`, `clang` (the pass -plugin), `ffmpeg` (videos), python with numpy and Pillow (charts). +plugin), `ffmpeg` (videos), python with numpy and Pillow (charts). The +`sqlite` scene also needs SQLite's amalgamation (`-Dsqlite=DIR`, the +directory of `sqlite3.c` and `sqlite3.h`; by default +`~/05-genizah/sqlite/sqlite-amalgamation-3500400`) and `objdump`; where +the directory is not there the scene is not made, and the rest builds +and tests as before. Dependencies are by path (`..` is ztrace, `../../sketchbook`, `../../02-pardes-code`); `zig-pkg` is a symlink to pardes's. @@ -72,6 +77,19 @@ 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)`. +## The scenes + +| Scene | Shows | Split, lens | Recording | +| --- | --- | --- | --- | +| `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` | +| `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` | +| `gallery` | every block in its states | all three | `gallery` | + ## The blocks The catalogue's layers, and where each block is. Every block is drawn in @@ -81,13 +99,13 @@ every state the code has in the `gallery` scene. | --- | --- | --- | --- | | 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` (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` | +| | `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 | | 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; `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 | +| 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 | +| | `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 | | 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 | @@ -118,6 +136,7 @@ and no canary stepped through that the source does not say. | `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 | +| `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 | 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 @@ -135,31 +154,41 @@ holds is named from its module's first mapping (`list+2c89`). 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, 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 | +| | 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.) What fires, and why it is left: -- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 22.28 are the +- CROWD: fib 12.05 and 27.20, list 30.62 and 32.18, sort 17.58 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). + 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 + 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). +- 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. ## What is not done @@ -169,17 +198,35 @@ What fires, and why it is left: - 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. + 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). -- 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. +- 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). - 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. +- A recording holds the bytes it has seen, each as last seen: it cannot + tell a byte read again and unchanged from one not read since. Memory + nothing watches (SQLite's page cache) is read at a stop only where a + pointer leads (32 bytes), so a view of it says what the stop read + (`hexdump.Fields.seen`); a syscall's buffer is shown as the kernel took + it, from its capture. The recorder should say what it read at each stop. +- A frame's file and line are known only where the recording stopped in + it: return addresses are recorded with names, not lines, so a deep + backtrace's older rows have none. +- 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). - `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. |
