summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md505
1 files changed, 384 insertions, 121 deletions
diff --git a/design/README.md b/design/README.md
index a6cc6dd..e465e8e 100644
--- a/design/README.md
+++ b/design/README.md
@@ -37,6 +37,12 @@ scene that draws every block in every state is the test of this page.
and a moment.
8. **Low level first.** The bytes change, the tie carries it, the drawing
reacts. A cause is always on screen before its effect.
+9. **Down is deeper, and what acts together sits together.** The idea
+ over the source, a line over its instructions, a call over its callee,
+ the program over the kernel. Execution goes down and across; what it
+ means comes back up. A pointer and its target, a call and its callee, a
+ drawing and its bytes are neighbours
+ ([direction and nearness](#direction-and-nearness)).
## Vocabulary
@@ -55,23 +61,24 @@ this table.
| | [`pin`](#pin) | a register's or a variable's name at the thing it points to | `row`, `under` |
| | [`bracket`](#bracket) | a span marked at its edge | `quiet`, `tie` |
| | [`tag`](#tag) | a panel's title bar | `focus`; `note` or `legend` |
+| | [`width`](#width) | an access's size in byte cells, where no register says it | 1, 2, 4, 8 cells; a count past 8 |
| 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop; opens a `loupe` |
| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) |
| | [`slot`](#slot) | a word of the stack and its chain | pins; `free` |
-| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` |
-| | [`line`](#line) | a line of source | `current`, `trail`; wide numbers |
-| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run; wide address |
+| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside`, `waiting`, `pass` |
+| | [`line`](#line) | a line of source | `current`, `trail`, `waiting`; wide numbers |
+| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs (`size`, `protected` among them), marks per byte; wide address |
| | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` |
| | [`arc`](#arc) | a pointer to a row of the same panel, drawn | standing, `touched`; a stub |
| 3 panel | [`registers`](#registers) | all seventeen | |
| | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | 8 or 6 slots |
-| | [`backtrace`](#backtrace) | the call chain as rows | in the `none` split; the view of `calls`; a lens's drawing |
+| | [`backtrace`](#backtrace) | the call chain as rows, newest at the bottom | in the `none` split; the view of `calls`; a lens's drawing |
| | [`source`](#source) | a window on the file | 14, 8 or 10 lines |
-| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows |
+| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows; a [`descent`](#descent): a window a call deep, the kernel at the floor |
| | [`lens`](#lenses) | a drawing of some state over the program's two columns, and in the third the pane it is a view of | `beside`, `subject` |
| | [`hexdump`](#hexdump) | memory, a `bytes` row a line | typed or by `fields`; `more` rows; `seen`; `given`; `memory` |
| | [`loupe`](#loupe) | the memory round a pointer's target, floating over the context | two at most, in depth |
-| | [`nodes`](#nodes) [`array`](#array) [`calls`](#calls) `heap` `syscalls` `pages` | the drawings a lens can hold | |
+| | [`nodes`](#nodes) [`array`](#array) [`calls`](#calls) [`syscalls`](#syscalls) `pages` | the drawings a lens can hold | `nodes` in two rows, a `bin` heading the second |
| 4 tie | [`thread`](#4-ties) | the current line is these instructions | standing |
| | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin`; a stub when that is out of view |
| | [`projection`](#4-ties) | these bytes are that part of the drawing | for a step |
@@ -85,6 +92,7 @@ this table.
| | [`card`](#clock-and-caption) | a title, the legend: no program running | |
| 6 verb | [`fire` `arm` `strike` `cool` `read` `extend` `link` `project` `travel` `advance`](#6-verbs) | what one block does | |
| | [`open` `close`](#6-verbs) | what a loupe does | |
+| | [`descend` `cross` `ascend`](#6-verbs) | what a descent does: a call followed down, a system call, a return | |
| | [`dive` `surface` `flash`](#6-verbs) | between the map and the working frame | |
| | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | |
@@ -247,6 +255,7 @@ Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth.
| --- | --- | --- |
| `number`: a field read as a number, or left to the eye | primary | raised, one rect a field |
| `pointer`: a field that is one | the region it points into | raised, one rect a field |
+| `size`, `protected`: malloc's words, read as below | primary: what is stored is not where it points | raised, one rect a field |
| `text`: a field read as text | a string's | raised, one rect a field |
| `loose`: a byte of no field: the allocator's between allocations, a struct's padding, what lies past the thing the dump is of | dim | none |
| `unread`: not observed at the stop shown | two 4-unit squares, faint | none |
@@ -352,6 +361,31 @@ serifs 6 or 7, in the ink of the tie it ends.
primary under focus and dim otherwise. Ranged right, a `note` (Go 18,
faint) or a `legend` (words in Go Medium 18, each in its ink, 14 apart).
+### width
+
+How many bytes a memory access touches, drawn as that many byte cells,
+where nothing else in the instruction says it. It replaces the
+disassembler's size words (`byte ptr`, `dword ptr`, `qword ptr`), which
+are dropped from every operand ([`insn`](#insn)).
+
+- **Form.** Cells 5 wide and 10 high, 7 apart, in `dim`, standing on the
+ baseline 3 after the operand's `]`; what follows the operand goes on 4
+ after the last cell: `[rbp - 0x60]▮▮▮▮, 0x10`. One cell for a byte, two
+ for a word, four, eight. Wider (`tbyte`, `xmmword` and up): eight cells
+ and the count in faint mono 20.
+- **When.** Only where no register outside the brackets of the same
+ instruction has the access's size, and the mnemonic does not fix it:
+ `cmp [rip + 0x11018b]▮, 0` (an immediate), `mov [rbp - 0x60]▮▮▮▮,
+ 0x10`, `movsxd r10, [rbp - 0x30]▮▮▮▮` (the register is 8, the read 4).
+ Not on `mov rdi, [rdi + 8]`, `mov [rbp - 0x38], eax`, `push`, `pop`, a
+ `call` or `jmp` through memory (always 8), `lea` and the padding `nop`s
+ (they touch nothing).
+- **Why cells.** A numeral under mono 20 breaks the floor; a suffix on the
+ mnemonic (`movl`) is a second syntax. A byte is already a cell in every
+ dump, so four cells read as four bytes.
+
+Mock 17.
+
## 2. Rows
Every row is 24 high and one line. None wraps; what does not fit is cut at
@@ -415,19 +449,23 @@ An instruction, pwndbg's way: what it is, and what its operands are now.
| 31 | jump lane | a 2-unit line in trail gold from a jump that was taken to the row it landed on, head 7 by 8 |
| 40 | address | code ink, `lead` |
| 134 | line | the source line this run of instructions came from, ranged right in three characters, faint; on the first row of each run only; gold and bold for the current line. Wide numbers (see [`line`](#line)) widen it, and every column right of it moves by the extra: mnemonic, operands and annotation, the row's room 12 characters less for six digits |
-| 180 | mnemonic | keyword, bold |
-| 264 | operands | as the disassembler writes them, whole; a jump's or call's target is an `address` in code ink |
+| 180 | mnemonic | keyword, bold; `nop` and `endbr64` faint, with their operands: padding, which touches nothing |
+| 264 | operands | as the disassembler writes them, whole, less the size words (`qword ptr `): a [`width`](#width) after the bracket where no register says the size. A jump's or call's target is an `address` in code ink; a PLT stub's, named by the stub: `401070 open@plt` |
| 564 | annotation | from 564, or a character after operands that run past it; a chain, cut at its far end by the chain's rule |
+**Wide addresses.** An address of more than seven digits (a library's
+twelve, `7ffff7d10fc5`) moves every column right of it by the extra, 12 a
+digit: in libc the mnemonic is at 240, the annotation at 624. The width is
+the window's own: in a [`descent`](#descent) the caller's window does not
+move when libc's opens under it.
+
**Room.** The row holds 50 characters from 264, to 12 from the panel's
edge. Operands are never cut where the row has room, and never inside
`[]`: we do not hide what the instruction says. When the operands and the
whole annotation do not fit, in this order:
1. the annotation moves left to where it just fits, never left of 564;
-2. a size word (`qword ptr `) goes from a memory operand whose size a
- register operand gives: `mov rax, [rbp - 0x28]`. Nothing is lost;
-3. the operands give way to the annotation: they end where it begins, in
+2. the operands give way to the annotation: they end where it begins, in
a faint `…`. A cut that would fall inside `[]` falls before the `[`,
and the annotation's first hop is the address the brackets named.
@@ -437,6 +475,8 @@ whole annotation do not fit, in this order:
| `ran` | trail bar, newest of three brightest; keeps the annotation of what it did |
| `ahead` | plain; only static annotation (a callee's name) |
| `outside` | another function's: plain, as `ahead`; over its first row a rule, and its name in that row's annotation column, dim. Past the program's text (padding, a section's end): faint |
+| `waiting` | a call whose callee's window is open under it, in a descent: the plaque's place ringed (a 2-unit primary frame 24 by 24, a primary head in it), as a waiting call node is; no wash. Its annotation is the call in C's form: `open("note", O_RDONLY)` |
+| `pass` | a stub's jump, gone through on the way down: a trail bar; the call lane runs on from it |
**The annotation**, by what the instruction does:
@@ -445,22 +485,33 @@ whole annotation do not fit, in this order:
| reads memory | a chain from the address it computes: `28b41098 → 28b41070 ◂ 9`. Before the step, where it will look; in the step its first hop is `read` |
| writes memory | the same chain; the value after `holds` is `struck` |
| only sets a register | a small `reg`: `rax 28b41090 ◂ 4` |
-| jumps on a condition | `taken` in primary, or `not taken` in dim; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37` |
-| calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there |
+| compares or tests | the two values it compares, ` : ` between, faint: `3 : -4096`; then the flags it leaves, those the conditional after it reads (CF ZF SF OF when none follows): set on a chip as rip's are, clear in dim lower case: `3 : -4096 CF zf` |
+| jumps on a condition | `taken` in primary, or `not taken` in dim, then `· reads` and the flags it reads, as the compare drew them; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37`. While it is current, the chips on the row that set them are framed as read with it (an `echo`), and rip's |
+| computes an address (`lea`) | `=` and what it made: an address and its chain (`= 402004 "note"`), or a number. With room, the sum first, each register's value in its ink: `rbp 7fffffffed00 - 0x30 = 7fffffffecd0` |
+| calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there. Through a PLT stub: the function the stub reaches, `open` (or `the resolver` while its GOT slot is still lazy). Once it has run: the call in C's form and its result, `open("note", O_RDONLY) = 3` |
+| calls or jumps through memory or a register | where it goes: `→ 7ffff7d10ec0 open`; then, faint, where that was read: `· read from open@got, 403fd8`. Out of room, the slot goes first, then the target's digits; its name stays: `→ __pwrite64` |
+| reads a place the C library's layout names | the name, then the value: `fs:[0x28]` is `the stack's canary 191a6a1f012bed00` |
+| repeats (`rep stosq`, `rep movsb`) | the count and the step: `rcx 12 · 8 bytes each`, the destination's chain after. Stepped by instruction a `rep` stays current while rcx counts down, an iteration a step |
| returns | `→ 10018b0 main+80` |
-| makes a system call | its name and arguments by name, as a call; the kernel's rows hang under it on vellum |
+| makes a system call | its name and number, `openat nr 257`; its arguments hang under it by name, as a call's; in a [`descent`](#descent) the kernel's window opens under its window |
Mocks 9 to 11 show the read, the register-setter, the taken jump and
`outside`; 12 a call with its argument, a write, and operands longer
-than 24 characters with the annotation moved right of them. Return and
-syscall annotations are not drawn.
+than 24 characters with the annotation moved right of them; 14 an
+indirect call by name; 16 a call through the PLT, `waiting`, `pass`, a
+system call; 17 a compare and the conditionals reading it, a `lea`, a
+named place. A `rep`, and the flags' echo, are not drawn.
### line
The number ranged right in three characters, faint; the text from 64, in
the four code inks; 67 characters, then a faint `…`. `current`: gold
plaque on the number, the wash across. `trail`: the bar, for the last three
-other lines run.
+other lines run. `waiting`: the pc is in code with no source (libc, a PLT
+stub, the vDSO) under this line's call: the number ringed, a 2-unit
+primary frame where the plaque would be, no wash; the source's tag says
+where the pc is (`main waits at line 6 · the pc is in libc's open`), and
+the thread waits with it (primary, 2 units).
**Wide numbers.** The number column is as wide as the program's largest
line number, three characters at least: sqlite3.c's 262 899 lines take
@@ -491,6 +542,23 @@ twelve put them at 190, and the reading at 698 (508 after the first byte,
as always). A dump sets this once, by the widest address in its
window, so its rows keep one column.
+**Malloc's words**, for a scene about the allocator (elsewhere the size
+word is the faint note above):
+
+- `size`: a chunk's size word. The reading is the size, the three low
+ bits cleared, in hex as malloc's sizes are read (`0x20`), then the bits
+ as rip's flags are drawn, `A M P` (not the main arena, mmapped, the
+ chunk before in use): set on a chip, clear in dim lower case:
+ `0x20 a m P`. A bit that changes is struck and held on its chip.
+- `protected`: a pointer glibc stores safe-linked, the pointer xor its own
+ address shifted right by 12. The bytes are what is stored, in primary
+ (`55 54 40`); the reading is what they protect, `→ 405050`, or `NULL`,
+ then the mask, faint: `→ 405050 ^ 405`. Its [`arc`](#arc) goes to the
+ pointer it protects. A NULL so stored is not zero (`05 04`, 405), which
+ the reading says.
+- A field may carry a note from the scene, Go 18 faint, after its reading
+ or as its reading: `key`, `slots left · 1 in the bin`, `the old link`.
+
The reading replaces a hexdump's text column: where bytes are text the
reading is the text, in quotes; where they are a pointer it is the address,
so a little-endian pointer is read without leaving the dump. It is a list,
@@ -620,12 +688,16 @@ rsp+48`), and `· the frames they belong to`.
### backtrace
-`call` rows, newest on top. A panel of its own in the `none` split, four
+`call` rows, the oldest on top and the newest at the bottom: a call adds
+a row under the others and a return takes it away, as the calls tree
+grows down beside it. `#n` keeps gdb's numbering, `#0` the newest, gold.
+A panel of its own in the `none` split, four
and then a count, under the stack; the view panel of a [`calls`](#calls)
lens, seven; the drawing of a [`backtrace` lens](#lenses), eleven as
-subject and five beside; in the other splits the stack's spans carry it.
-More frames than rows: the oldest go, and the tag's note counts them,
-`newest on top · 2 more`. On the map it is whole.
+subject and five beside, its `#0` just over the source line it is at; in
+the other splits the stack's spans carry it.
+More frames than rows: the oldest go from the top, and the tag's note
+counts them, `newest at the bottom · 2 more above`. On the map it is whole.
On a stop far from the last (a [`continue`](#6-verbs)) the chain changes
as rows making room: the frames that end fade out (12 f); the frames both
@@ -661,6 +733,55 @@ Nine (four, the pc, four) when the lens is the subject.
On the map the column is 69 rows: the function whole when it fits, with
its neighbours round it.
+A call the narration does not follow moves the window to the callee, as
+above: the stack's spans and the backtrace carry the depth. A call it
+follows opens a descent.
+
+### descent
+
+The disassembly a level up: a call followed down. The panel becomes a
+stack of windows, one a call deep, the caller's on top and each callee's
+under the row that called it, and under the deepest, while a system call
+is made, the kernel. Down is deeper, and the way back up is drawn.
+
+| Part | Drawn |
+| --- | --- |
+| a caller's window | its call row, `waiting`, the row before it and the row it will return to: three rows. The nearest caller gets the rows the deepest does not use, round its call row |
+| a head | a row: a 2-unit rule across, the callee's name at 40 (Go Medium 18, primary), what it is ranged right (Go 18, faint): `libc.so.6 · no source`, `the PLT · its jmp reads open@got, 403fd8`, `vdso · the kernel's code, run here` |
+| the call lane | 2 units, primary, from the waiting ring at x 14 straight down to the head, turning in to a head 7 by 8 before the name. It is part of the panel, as the jump lane is, and not a tie of the budget |
+| a stub | its rows whole (a PLT entry is three); once its `jmp` has gone on, its window keeps that row, `pass`, and the lane runs on from it to the next head |
+| the deepest window | as long as it needs: a stub whole, else the rows round the pc as the panel's; four of its rows under a `syscall` hold the call's arguments |
+| the kernel | the floor: solid vellum, its head `the kernel` and the call (`openat, system call 257`); the call in C's form; `returns` and the value (struck as it lands), with what the crossing clobbered (`rcx, r11`). The crossing lane: 3 units, vellum, from the `syscall` row's plaque down to the vellum, its head in ink on it |
+| the panel's tag | the deepest function and its module: `open · libc.so.6` |
+
+In seventeen rows, the call to `open` at its `syscall`: main's three, the
+stub's head and its `pass` row, the wrapper's head and eight rows, the
+kernel's head and two rows ([mock 16](mock/16-descent.png)).
+
+- **Depth.** Three windows of code at most, and the kernel. A longer chain
+ keeps the first and the last two; the ones between are one row, `more`'s
+ arrow and `2 calls: fib fib`. The stack's spans and the backtrace hold
+ the whole chain.
+- **The source** stays on the deepest frame that has source, its line
+ `waiting`, while the pc is in code without it. Into a function of the
+ program's own the source follows the pc as it always does; the call's
+ line is in its waiting row's annotation.
+- **Any call.** The program's own function: its window, its lines.
+ libc's: no source, its symbol and module. A PLT stub: its three rows,
+ the GOT slot named in its head; under lazy binding its `jmp` goes back
+ into the PLT and to the loader's resolver, which is one row of `more`
+ (`→ … _dl_runtime_resolve, 412 instructions`), and the GOT slot it
+ writes is struck in memory, where the data is. The vDSO: its window, no
+ kernel under it (the point of it); what it reads is the `[vvar]` page.
+- **Up.** A `ret` closes the windows under its caller's, bottom first;
+ the caller's window grows back to the panel and its call row is `ran`,
+ its annotation the call and its result. A stub jumped through closes
+ with the function it jumped to: the return goes straight to the caller.
+- **On the map** the column is the descent whole: each window its
+ function, whole where it fits, the kernel's under the last.
+
+Its motion is [`descend`, `cross`, `ascend`](#6-verbs).
+
### lenses
A lens is the band across the top of the stage: **a drawing, over the
@@ -674,10 +795,9 @@ the drawing keeps its subject size and the view is its region whole.
| --- | --- | --- | --- |
| `nodes` | boxes of a value and a pointer, arrows between them | a `hexdump` of the nodes' bytes | 9 to 11; 2 at camera scale |
| `array` | cells, index pins, flights for a swap | a `hexdump` of the array's bytes, an element a run | 7 at camera scale |
-| `heap` | the heap to scale: chunks, bins | a `hexdump` of the chunk in hand | 4 at camera scale |
| `calls` | a call tree under its caller, results on the shoulder | the `backtrace`; each node is also a `call` span on the stack, tied by `project`. Subject only: a tree needs the height | 12; 1 at camera scale |
| `backtrace` | the call chain itself, as `call` rows (eleven as subject): how the program came to be here, when that is the story and no one function's calls are | a `hexdump` by `fields` of what the newest call was handed (the struct an argument points at, a buffer), at its stop | 13, 14 |
-| `syscalls` | the kernel's side, on vellum: the calls so far, the call decoded, the bytes it holds | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 3 at camera scale |
+| `syscalls` | the calls so far, as strace writes them, oldest on top; the kernel's own side is the [`descent`](#descent)'s floor | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 14; 16; 3 at camera scale |
| `pages` | the far view: pages, system calls over time | the mappings, a row each | 8 |
| `hexdump` alone | bytes and their text | itself | 5, in its first-pass form |
@@ -685,6 +805,12 @@ the drawing keeps its subject size and the view is its region whole.
touch, each a `hexdump` kept round what was read or written, typed where
the recording types it; a lens's view is a window onto it.
+There is no heap lens. libc's heap is a scene drawn with these blocks:
+`nodes` in two rows (the program's list over malloc's free list), its view
+the chunks by `fields` (`size`, `protected`), the free list as `arc`s, a
+`loupe` on the tcache ([the heap scene](motion.md#a-scene-libcs-heap-from-the-inside),
+mock 18).
+
A scene may change its lens where it stands: the drawing fades out (12
f), then the next fades in (12 f) and its elements come in as at
`establish`; a view the two share stays. The split does not move, so this
@@ -714,6 +840,24 @@ dim slash. **Above** each node its address, in its region's ink: the same
digits as its row in the dump. **Under** it, its pins. Marks on a half:
`read` frames it, `held` is the bar along its bottom edge.
+**Two rows**, for chunks that change hands (the heap scene): the
+program's list on top, from its variable's pin, and under it the
+allocator's free list, both in list order, 110 apart. A node goes from
+one row to the other when it is freed or taken back (`travel`, 36 f). The
+boxes are 136 wide, so a stale word can be read in the value's half.
+
+- A node the allocator holds is drawn `freed`: its outline dashed 12 on
+ 8, its first word's half the well and the link's square (glibc's tcache
+ keeps the link where the value was), the second half hatched with `key`
+ in faint. The arrow is the link as it protects, not as stored.
+- **`bin`**, the second row's head: a raised box 160 by 44 at the row's
+ left, the bin's name in mono 20 (`tcache 0x20`), how many chunks it
+ holds on its shoulder as a call's result is (a square of 30, mono 25),
+ an arrow from its right edge to the first chunk. Before the bin exists,
+ the box dashed and faint (`dummy tcache`). The count is what the bin
+ holds, worked out from what glibc stores (2.44 stores the slots left,
+ 16 less it; the loupe on the tcache shows both).
+
### hexdump
`bytes` rows, sixteen a row, a window of the region kept round the rows
@@ -732,7 +876,8 @@ Its runs come one of two ways.
- **`fields`**: a region the scene names (a base, a length, the memory's
region ink) and the fields it gives it, each `at` an offset, `len`
bytes long, read as a `number` (low byte first, or `big`: high byte
- first, as a file format stores it), a `pointer`, `text`, or `bytes`,
+ first, as a file format stores it), a `pointer`, `text`, malloc's
+ `size` or `protected` ([`bytes`](#bytes)), or `bytes`,
left to the eye: on raised paper with no reading. A byte of no field is
`loose`. A field is a run, cut where a row ends. This is how a real
program's memory is drawn when the debug info does not type it, or the
@@ -821,29 +966,35 @@ left out is counted, never dropped.
### syscalls
-The kernel's side, on vellum (solid vellum is the kernel): the calls so
-far, newest on top, each with what it returned; the call in hand,
-decoded: its name, its arguments by name beside the registers the call
-takes them in (`rdi fd 3 "t.db"`), `returns`; and the bytes it was given
-or filled, ten a row, two rows. Its view is a [`hexdump`](#hexdump) by
-`fields` of the buffer, `given`.
+The program's conversation with the kernel. The drawing is the calls so
+far as strace writes them, a row each, oldest on top and the newest at
+the bottom: the name in bold, the arguments by name with their values
+(`fd 3 "t.db"`, `buf 538b28`) where the recording has them, ` = ` and
+the result, the newest's with the turned corner. Its view is a
+[`hexdump`](#hexdump) by `fields` of the buffer, `given`. The band is not
+the kernel and is not on vellum: the kernel is under the program, the
+floor of a [`descent`](#descent), where the call is made. A crossing
+stepped over (a line that calls libc's wrapper, not followed down) opens
+the same window under the call row: the wrapper is not shown, and the
+kernel is still under the program.
A **crossing** is a step that makes one system call; its timetable is
-[motion.md's](motion.md#a-system-call). What it may claim:
+[`cross`](#6-verbs) and [motion.md's](motion.md#a-system-call). What it may claim:
- A register is framed as carrying an argument only while it holds that
argument at the stop shown. Stopped in the caller of libc's wrapper,
`pwrite64`'s buffer and count are in rsi and rdx, but its descriptor is
not yet in rdi nor its offset in r10: those two are not framed, though
- the kernel's rows name them.
-- Nothing on the kernel's side changes before the arrow down arrives.
- `returns` takes the value before the arrow back leaves, rax is struck
+ the kernel's window names them. Followed down to the `syscall` row,
+ all of them are.
+- Nothing on the kernel's side changes before the crossing lane reaches
+ it. `returns` takes the value before the answer leaves, rax is struck
as it lands, and everything else the step changed (the registers the
- wrapper and the call clobbered, pins, links, a result stored in memory)
- waits for rax.
+ call clobbered, pins, links, a result stored in memory) waits for rax.
+ The log's row comes in with `returns`.
- A step that makes several calls (a continue through a library) is not
- a crossing: the list takes them, oldest first, 2 f apart, each fading
- in; the newest is decoded; no arrow, no bytes.
+ a crossing: the log takes them, oldest first, 2 f apart, each fading
+ in; no lane, no kernel window, no bytes.
### loupe
@@ -933,6 +1084,7 @@ projection):
| a lens's bottom lane, 8 above its edge | what arrives from below: a link to the pin under its node; a projection to a call node |
| a lens's top lane, 4 under its tag | a projection from the view, to the bracket over its node's address |
| a panel's pin lane | a link's last leg to a `row` pin, or its stub |
+| the disassembly's call lane, x 14 | a descent's call lane, down from a waiting row to its callee's head; the crossing, down to the kernel's window, and the kernel's answer back up it |
| none | a loupe's stem: from its pointer straight to the loupe, over the row's empty end, or the gap between a loupe's row and the loupe it opens |
Ties that climb from the state column take the left lane and arrive from
@@ -995,6 +1147,76 @@ rest, and the minimap shows it.
| lens band (the drawing and its view) | | 13% | 21% |
| caption band, with the minimap | 10% | 10% | 10% |
+### Direction and nearness
+
+**Which way things go.**
+
+- **Down is deeper.** Under each thing in the program column is what it
+ becomes: the idea (the band) over the source, a line over its
+ instructions, a call over its callee ([`descent`](#descent)), the
+ program over the kernel. In the state column the registers are over
+ the stack. A call goes down and a return comes up; in the backtrace and
+ the calls tree the newest is lowest.
+- **Memory is where it is.** A dump, the stack and a loupe are in address
+ order, low on top, because a row's place there is its address: so the
+ stack's newest frame is its panel's top, and an arc or a jump's line goes
+ whichever way the addresses do. It is the one exception.
+- **Execution goes down and across; meaning comes back up.** A step's
+ cause is a row of the program column. Its effects cross the gutter into
+ the state (an instruction to the register it writes) and go down it (a
+ register into the stack); what they mean climbs into the band (from the
+ stack up the gutter, from a register to a pin under a node) and crosses
+ back to the drawing from the bytes beside it. An answer comes back up
+ the way its call went down: a return to its call row, the kernel's answer
+ up the crossing lane to the `syscall` row, then rax.
+- **A still is read the other way, top down**: what it means first, then
+ how it is made. The band is on top because the idea is what a scene is
+ about.
+- **Every tie runs one of those ways.** In the context down or right (the
+ thread, a link to a slot, a loupe's stem, the call lane and the
+ crossing); into the band up, then left (a link to a pin, a projection).
+ None runs against them.
+
+**What sits together.** Things that act on each other are neighbours,
+each pair in one place:
+
+| Pair | Where |
+| --- | --- |
+| a line and its instructions | the source over the disassembly; the thread between |
+| an instruction and what it changes | the change in its own row's annotation; the register across the gutter |
+| a pointer and its target | the target's pin; in one panel the `arc`; a `loupe` hung under the pointer |
+| a call and its callee | the callee's window under the call row ([`descent`](#descent)) |
+| a system call's arguments and the kernel's side | the arguments under the `syscall` row, the kernel's window under them |
+| the drawing and its bytes | side by side in the band, the projection across the gutter at one height |
+| a call tree and its frames | the tree and the backtrace beside it, both down to the newest; a frame's span on the stack |
+| the flags a compare sets and the jump that reads them | their two rows, framed together while the jump is current |
+
+**The audit.** Against these rules, what moved:
+
+| Where | Was | Now | Why |
+| --- | --- | --- | --- |
+| the `syscalls` lens | the kernel's side, on vellum, in the band over the program | the kernel under the `syscall` row, the descent's floor; the band holds the calls so far as strace writes them | the kernel is under the program, and a call's arguments and the kernel's side are now neighbours (mock 14) |
+| the backtrace: a panel, the calls lens's view, the backtrace lens, the map | newest on top | newest at the bottom, `#0` last | a call goes down: it reads as the tree beside it does, and the backtrace lens's `#0` sits over the source line it is at (12, 13, 19) |
+| a call followed into a function | the window went to the callee; the call row left the screen | the `descent`, when the scene follows the call | the call and its callee are neighbours, and the return has a row to come back to (16) |
+| `qword ptr` and its kin | in every operand | gone; a `width` where no register says the size | the operand is shorter and the width is shown only where it is news (17) |
+
+What stays, and why:
+
+- **The band's view over the registers.** It is memory over the CPU,
+ against down is deeper; but under the registers it would be 300 units
+ from the drawing made of it, and the projection between them would cross
+ the frame. The band is the idea twice, as drawn and as bytes, and the
+ drawing and its bytes being side by side matters more.
+- **The registers beside the disassembly**, not under it: an instruction
+ and its register are across the gutter at about one height.
+- **The map** keeps the frame's order across its four columns: the drawing
+ and the source, the disassembly (a descent whole, the kernel at its
+ foot), memory over the registers, the stack. The backtrace stays at the
+ foot of the first column, beside the disassembly it is the chain of.
+- **The lenses**: a list left to right in list order, an array by index,
+ a tree down, the far view's time left to right, a loupe hung under its
+ pointer. None goes against the rules.
+
### The map and the minimap
**The map** is the working frame unfolded: every panel at its full length,
@@ -1110,6 +1332,9 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves:
| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and the map becomes the minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; the map, veiled, goes the same 72 f to the minimap's place, its scale from a half to a twentieth, so the windows rise out of it as it falls away; their outlines stay on it and land as the minimap's windows. 72 to 96: the drawing, whose sizes differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: the frame's tags, rules and lanes fade in; the veil on the map lifts as it lands. 96 to 132: still |
| `surface` | from the working frame to the map | the dive backwards, a little quicker: 0 to 12 the tags, rules and lanes fade out; 12 to 84, `glide`, the panels shrink into their windows as the minimap grows to fill the frame; 84 to 96 its veil lifts; then the map is still 36 f before anything plays on it |
| `flash` | the minimap, at a mark no window shows | a ring 8 across in the mark's colour draws out to 14 and is gone, 12 f, with the mark's own strike or read |
+| `descend` | a call the narration follows down | 0 to 12 fire on the call row; rsp struck (24); the stack slides and the return address is struck (30 to 60), as for any call; then 66 to 84 the caller's window closes round its call row (the rows it gives up fade, 12 f; its three glide to its top, 18 f, `glide`); 72 to 84 the call row's plaque becomes the ring; 84 to 102 the call lane draws down from the ring, head first, `standard`; 96 to 108 the callee's head fades in rising 8 as the lane reaches it; 102 to 126 its rows, top down, 2 f apart, 12 f each; 126 to 138 the advance: the plaque lands on the callee's first row, and the source line goes `waiting` (6 f) where the callee has none. Through a stub's `jmp`: the stub's window shrinks to that row, `pass` (18 f, `glide`), the lane runs on to the next head (18 f), the next window comes in the same way |
+| `cross` | a `syscall` row, in a descent | 0 to 12 fire; 18 to 36 the registers that carry the call framed as read, 6 f apart, the argument rows under the row with them (`echo`); 48 to 72 the crossing lane draws down, 3 units, vellum; 66 to 78 the kernel's window opens as it lands, the vellum filling down from the lane's head; 78 to 90 its head and the call fade in, 6 f apart; the work (bytes given or filled, motion.md's chart); `returns` struck; then the answer climbs the lane (24 f) and rax is struck as it lands, the clobbered registers 6 f apart after it, the log's new row fading in (secondary); hold 36; the advance: the kernel's window draws back up into the lane (12 f) and the lane into the plaque (12 f) as the plaque moves on |
+| `ascend` | a `ret` out of a descent's window | 0 to 12 fire; 18 to 24 the return address framed as read on the stack; rsp struck (36); 48 to 72 the window closes, its rows fading bottom up, 2 f apart, 12 f each, its head last; 72 to 84 the lane draws back up into the ring; 84 to 102 the caller's window grows back (`glide`), the rows it gave up fading in; 102 to 114 the ring becomes a trail bar, the call row's annotation takes the result (6 f), and the plaque lands on the row after the call; the source line from `waiting` to `current` |
| `arc` | a pointer to a row of its panel | written: with the arm (s−12) the old arc goes dashed; from s+6 it fades (12 f) while the new one draws from the pointer's row along its lane to the target, head first, 12 f, `standard`, at full ink; with the cool at the advance it quiets to standing (24 f). Read: to full ink with the read (6 f), back with the advance. Overwritten with a target off the panel or NULL: it fades from s+6 (12 f). A lane change glides 12 f. Scrolled: it rides its rows, fading as its target leaves. At a run 8 f, at a sprint none |
| `advance` | the current marks | last. The thread, the plaques and rip move together: 12 f to an adjacent row, 24 f up to eight rows, `standard`; farther, out and in over 6 f. A taken jump's line draws in the jump lane with it |
| `cascade` | a step | `fire` (12); then its effects a level at a time, 18 f apart: CPU (`reg`s, the pc's annotation), memory (`slot`s, `bytes`), the idea (the drawing, by `project`); each armed, then struck; hold 36 f after the last strike and 12 f a further value, 84 at most; `advance`; rest 24 f. A level with nothing on screen to change gives up its slot |
@@ -1124,7 +1349,8 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves:
A step is as long as its content: 0.8 s when only the line moves, 1.5 s
for one register, 2.0 s for a register and memory, 3.0 s for a call and 3.1 s
-for a return across three levels, 2.7 s for a swap.
+for a return across three levels, 2.7 s for a swap; 2.7 s to follow a
+call down, 3.6 s for a crossing (4.9 s when it moves bytes), 2.3 s back up.
## Composition
@@ -1133,8 +1359,8 @@ for a return across three levels, 2.7 s for a swap.
- The working frame holds the band and two columns; the band is two
panels, one over each column. The map holds the same panels, whole, in
four columns. A column holds panels. A panel holds a tag and rows,
- or (a lens) a tag and a drawing. A row holds atoms. Nothing nests
- deeper.
+ or (a lens) a tag and a drawing, or (a descent) a tag and windows of
+ rows under their heads. A row holds atoms. Nothing nests deeper.
- Every panel shows the same moment. A register from one stop beside a
stack from another is a lie, however small.
- A mark sits on an atom or a row, never on a panel. A panel's only
@@ -1188,20 +1414,24 @@ for a return across three levels, 2.7 s for a swap.
## The mocks
-`mock/context.py` draws 12 to 14, one function a block under the block's
-name; `mock/map.py` draws the working frame from a fresh recording of
-`targets/list` (9 to 11, 21), the map (19) and the dive (20);
+`mock/context.py` draws 12 to 14, 16 and 17, one function a block under
+the block's name; `mock/map.py` draws the working frame from a fresh
+recording of `targets/list` (9 to 11, 21), the map (19) and the dive (20);
`mock/dense.py` holds that recording's data and draws the marks sheet
-(15); `mock/gen.py` draws 1 to 8. Each working frame has a `-480.png`
-beside it; the map has its 1080p (`19-map-1080.png`).
+(15); `mock/heap.py` draws the heap scene's storyboard (18) from a
+recording of `mock/heap.c`; `mock/gen.py` draws 1 to 8. Each working frame
+has a `-480.png` beside it; the map has its 1080p (`19-map-1080.png`).
```sh
cd design/mock
python3 -B context.py && for n in 12-calls-subject 13-sqlite-row 14-sqlite-page; do
- resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done
+ resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done; resvg 16-descent.svg 16-descent.png
+resvg 17-operands.svg 17-operands.png
+python3 -B heap.py && resvg 18-heap.svg 18-heap.png && resvg -w 480 18-heap.svg 18-heap-480.png
python3 -B dense.py && resvg 15-marks.svg 15-marks.png
python3 -B map.py && for n in 09-context 10-context-step 11-context-lens 21-loupe 19-map; do
resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done # 20-dive.png it composes itself
+resvg -w 1920 19-map.svg 19-map-1080.png
python3 -B gen.py # 1 to 8, then resvg the same way
```
@@ -1210,17 +1440,20 @@ python3 -B gen.py # 1 to 8, then resvg the same way
| [9](mock/09-context.png) | `beside`, at rest: `targets/list` stopped at the load in `reverse` (`mock/list-dbg.txt`, moment 2) | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot` with offsets and roles, `pin` row; `call` spans; `insn` current, ahead, outside under a rule and its name; `line`; `bytes` by fields with number, pointer, loose; an `arc` standing in the view; `nodes` with pins under, two names on one; `thread`; marks current, held; the minimap, its windows |
| [10](mock/10-context-step.png) | the same, mid-step: the load done (moment 3) | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection`; the read pointer's `arc` at full ink; the minimap |
| [11](mock/11-context-lens.png) | `subject`, mid-step | the band at 296 and 200, the drawing a size up, a dump of seven, nine instructions, six slots; the minimap with the subject's windows |
-| [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments; `call` spans with arguments; the stack's row with offsets and a role; a `projection` from the return address to the new node; operands of 27 characters whole |
-| [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in |
-| [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the kernel's side in the band; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed |
+| [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments, newest at the bottom beside the tree; `call` spans with arguments; the stack's row with offsets and a role; a `projection` from the return address to the new node; operands of 27 characters whole |
+| [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing, `#0` at the bottom over its source line; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in |
+| [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the calls so far in the band, strace's way, the newest whole and held; the call through a pointer by its target's name, `→ __pwrite64`; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed |
| [15](mock/15-marks.png) | the marks sheet: `current`, `struck`, `held` as A (the first videos), B (the catalogue's) and C (a whiter reading), on rows of the list at the load and the store after it | the source's current line; the pc's row; rip; a struck and two held registers; a dump row struck on the one byte that changed and one held; a lens's cell held and struck; the same rows at 1.35 times |
| [19](mock/19-map.png) | the map, mid-step with a loupe open: the same moment unfolded on 3840 by 2160 ([at 1080p](mock/19-map-1080.png)) | the file whole; 69 instructions; memory, the registers, the backtrace whole; the stack from 16 words above rsp, continued at the third column's foot and folded into `more` at the process's start; the loupe as a panel beside memory; `arc`s in memory, the loupe and the stack (the frame chain left to the spans); the key; the thread across the gutter; the working frame's windows outlined |
| [20](mock/20-dive.png) | `dive`, four instants on one sheet, each at the working frame's size | frame 0 the map; 24 the windows bright, the rest veiled; 60 halfway, the panels rising out of the map as it falls to the corner; 96 the working frame with its minimap |
| [21](mock/21-loupe.png) | the working frame mid-step with a `loupe` open | the loupe hanging from rdi over the registers under it, its node framed, the chain 1004090 → 1004070 → 1004050 as `arc`s in one lane (the view withholds them while the loupe is open); the minimap with the loupe at its place on the map, outlined bright |
+| [16](mock/16-descent.png) | the syscalls scene's `open` followed down, four instants of the program column (`ztrace dbg` on `anim/tools/hello.c`, moments 1 to 6) | `descent`: main's window, the PLT stub's under it, libc's `open`, the kernel's window on vellum; `insn` `waiting` and `pass`; the call lane and the crossing lane; `line` `waiting` and the waiting thread; a PLT target named, an indirect jump's target, a `lea`'s result, a named place (the canary), a system call's number and its arguments hanging under it; libc's twelve-digit addresses moving their own window's columns; the descent closed again, the call `ran` with its result |
+| [17](mock/17-operands.png) | operands before and after, on real rows of list, hello and libc's `open`; then the row's detail | size words gone; `width` on an immediate store, a byte compare, a sign-extending load; padding faint; a compare's two values and the flags it leaves; conditionals reading them; `lea`'s sum; an indirect jump through `open@got` |
+| [18](mock/18-heap.png) | the heap scene, five instants: `ztrace dbg` on `mock/heap.c`, glibc 2.44, after each malloc and free | `nodes` in two rows, a `bin` heading the second (`dummy tcache` before the first free); a free chunk drawn `freed`, its link in its first word; `bytes` read as `size` (`0x20 a m P`) and `protected` (`→ 405050 ^ 405`), notes (`key`, `the old link`); the free list and the program's list as `arc`s; struck bytes, one byte of a pointer struck alone; a `loupe` on the tcache hung from the dump's row of its chunk |
| [1](mock/01-fib-recursion.png) | first pass | `calls` at camera scale |
| [2](mock/02-list-insert.png) | first pass | `nodes` at camera scale; `allocated` |
-| [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` |
-| [4](mock/04-malloc-glibc-musl.png) | first pass | `heap`; `freed` |
+| [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` (the kernel's side is now the descent's floor, 16) |
+| [4](mock/04-malloc-glibc-musl.png) | first pass | the allocator drawn to scale; `freed` (now a scene, not a lens: 18) |
| [5](mock/05-memory-write.png) | first pass | a byte grid: the old form of `hexdump`; `struck` and `held` in cells |
| [6](mock/06-title-legend.png) | | `card`, the legend |
| [7](mock/07-sort-swap.png) | first pass | `array`; `travel` |
@@ -1233,8 +1466,13 @@ the band.
**Specified, not drawn.**
- The `none` split, and the `backtrace` as a panel of its own.
-- `insn` annotations for a return, a system call, `not taken`, a jump out
- of the window; operands giving way (none in 9 to 14 needs to).
+- `insn` annotations for a return, a jump out of the window, a `rep`, a
+ `lea` with registers in its sum; the flags' echo; operands giving way
+ (none in 9 to 17 needs to).
+- The descent's motion, its fold of a deep chain, a lazy PLT's resolver
+ row, the vDSO, a descent into a function of the program's own, and the
+ descent on the map. The registers and stack beside 16's instants (the
+ strip is the program column only).
- `value` classes other than digit, small number and string.
- `armed`, `fault`, `attention` and the veil in the context.
- A `projection` from the dump for a write. A `link` to a `slot`, and its
@@ -1243,10 +1481,13 @@ the band.
- `unread` field bytes at a stop that saw only part of a buffer (the page
at stop 167, before the kernel took it).
- A calls tree small or folded.
-- `array`, `heap`, `pages` in the band.
-- A loupe opened from the stack, the disassembly or a dump; a loupe typed
- by `fields`; two in the working frame; a third closing the first.
-- The minimaps of 12 to 14: their recordings hold a stack of 64 words or
+- `array`, `pages` in the band.
+- The heap scene's working frame whole, its map and minimap (its places
+ are in [the scene](motion.md#a-scene-libcs-heap-from-the-inside)), a
+ node travelling between the rows, a bin of the unsorted or large kind.
+- A loupe opened from the stack or the disassembly (18 opens one from a
+ dump's row); two in the working frame; a third closing the first.
+- The minimaps of 12 to 18: their recordings hold a stack of 64 words or
less and no bytes round targets, so their maps would be mostly gaps.
- `surface`, `flash`, a window's outline gliding on the minimap.
- A local's name as a slot's role (the recording has none at these pcs).
@@ -1260,7 +1501,13 @@ instructions and their lines (12: `ztrace show` on
`addr2line`; 13 and 14: `ztrace show` on the sqlite scene's recording,
its source from SQLite's amalgamation, and the bytes of the struct and
the page as the scene's export shows them, the page's from the recording's
-capture of `pwrite64`). The frames' extents are read off the frame-pointer chain.
+capture of `pwrite64`; 16: `ztrace dbg` on `anim/tools/hello.c`, built
+`-O0 -no-pie -Wl,-z,now` and run under `env -i setarch -R`, its libc rows
+from that run's disassembly; 17: the same runs and `objdump -d` of
+`/usr/lib/libc.so.6`; 18: `ztrace dbg` on `mock/heap.c`, `x 0x405000 1024`
+after each malloc and free). The frames' extents are read off the frame-pointer chain.
+The older calls in 14's log show `(…)` for their arguments: this mock's
+data has only their names and results.
The dump's node bytes are what the chains and the program say the heap
holds; its allocator rows are glibc's layout, with the word nothing reads
drawn as never read. A recording made under ptrace has seen neither. The
@@ -1275,82 +1522,95 @@ still read.
## What this asks of the renderer
What the documents say and `anim/src` does not do, as read on 10 November
-(`theme.zig` as of 22:37: the marks and the stack's row are in; the 4K
-stage of the last round was never built, and is withdrawn); the tokens are
-under [Token changes](#token-changes).
+at 23:07. Since the last round `theme.zig` has the map and the minimap
+(`map.zig`), the loupe (`loupe.zig`), the `arc` and the dump's and the
+slot's new columns; whether `dive`, `surface` and `flash` are whole there
+is not checked here. The tokens are under [Token changes](#token-changes).
-1. **The map**: a second layout at 3840 by 2160 units, the same panels and
- rows, each panel at its full length ([the map](#the-map-and-the-minimap)):
- the source whole or 69 lines, the disassembly 69 rows, the registers,
- the backtrace whole, memory per region touched (32 rows, fieldless rows
- folded), the stack from rsp − 128 to its top, the drawing at its subject
- size, loupes at nine rows; packed into four columns by content, a panel
- continuing in the next column's free space under `continued`, the key
- in a column's left foot. It draws the thread and the marks, no link and
- no projection, and outlines the working frame's windows.
-2. **The minimap**: the map drawn at a twentieth in the caption band's
- right end (1664, 912, 192 by 108): text runs as strokes, blocks for tags,
- paper and loupes, the marks over them, the windows outlined; the clock's
- count moves left of it. `flash` for a mark no window shows. A window's
- outline glides with its scroll. The camera never takes it.
-3. **`dive` and `surface`**: a transition that draws each working panel
- in its own transform (scale and offset), from its window on the map to
- its place, while the map, veiled, is drawn in one transform from
- filling the frame to the minimap's rect; scales on their logarithms,
- `glide`; the panels 6 f apart in the frame's reading order (drawing,
- view, source, registers, disassembly, stack), each later one over the
- earlier, so that none crosses another mid-flight unseen. The camera
- moves one transform for the whole stage and `relayout` lerps boxes at
- one text size: neither does this. A sprint, a long run and a far
- `continue` are played on the map between a `surface` and a `dive`.
-4. **`arc`** ([`arc`](#arc)): in a dump, a loupe and the stack, the lanes
- at their left edge, the columns moved for them; standing and full ink;
- the frame chain only when touched; a loupe's rows withheld from a dump
- showing them.
-5. **The loupe** at the working frame's measures ([`loupe`](#loupe)):
- five rows, hanging from its pointer, the lift and the shadow; nine rows
- as a panel on the map; on the minimap a lift block, its target
- outlined.
-6. **Still from before**: the calls tree's small size and folds,
- `metric.span.name_max` 300, `time.caption_max` 12 s and `time.first_step`
- 4 s (5 s when a scene opens on the map).
+1. **Direction** ([direction and nearness](#direction-and-nearness)):
+ the backtrace with the newest at the bottom (`calls.zig` and
+ `context.zig` still write `newest on top`), the oldest dropped from the
+ top, `· 2 more above`; the `syscalls` lens's drawing as the log of
+ calls ([`syscalls`](#syscalls)), the kernel's side leaving the band
+ for the descent's floor.
+2. **The descent** ([`descent`](#descent)): the disassembly as windows a
+ call deep, each with its head row and its own address width; `insn`
+ `waiting` and `pass`; the call lane and the crossing lane; the kernel's
+ window on vellum; folding past three windows; on the map the column
+ whole. Its verbs `descend`, `cross`, `ascend`. With it, `line`
+ `waiting` and the waiting thread (primary, 2), and the source's tag
+ saying where the pc is.
+3. **Operands** ([`insn`](#insn), [`width`](#width)): every size word
+ dropped; a `width` of byte cells where no register of the instruction
+ has the access's size and the mnemonic does not fix it; `nop` and
+ `endbr64` faint.
+4. **The row's detail** ([`insn`](#insn)'s annotations): a compare's two
+ values and the flags it leaves, as chips; a conditional's `· reads`,
+ and its echo on the setting row and rip's flags while it is current;
+ `lea`'s `=`; an indirect call's or jump's target and the slot it was
+ read from, the target's name the last thing to go; a PLT stub named in
+ the operand (`401070 open@plt`) and the function it reaches in the
+ annotation; places the C library's layout names (`fs:[0x28]`, the
+ canary); a `rep`'s count; a system call's name and number, its
+ arguments hanging under it; a ran call in C's form with its result.
+5. **Malloc's words** ([`bytes`](#bytes)): field reads `size` (the size,
+ `A M P` as chips) and `protected` (the pointer protected, the mask,
+ the arc to the pointer), and a field's note.
+6. **`nodes` in two rows** ([`nodes`](#nodes)): the program's list over a
+ free list, a node travelling between them, the free form (dashed,
+ hatched `key`, its link from the first word), and the `bin` box
+ heading the second row.
+7. **Still from before**: the calls tree's small size and folds,
+ `metric.span.name_max` 300, `time.caption_max` 12 s and
+ `time.first_step` 4 s (5 s when a scene opens on the map), `time.dive`
+ and `time.flash`.
-**What the recordings must hold for the map**, with the tracer's options:
+**What the recordings must hold**, with the tracer's options:
-- `--stack 1024`: the stack from rsp to 1024 above it, at every stop, and
- the 128 bytes under rsp the tracer now keeps; the map's stack column is
- 69 slots and its continuation (about 90), the rest folded.
-- `--disasm 69`: 34 instructions above the pc and 34 below, with their
- lines; a function the window holds whole needs no more.
-- `--around 256`: 256 bytes either side of every telescope target and
- every touched address, clipped to its mapping: the map's memory column
- is 32 rows round what a step touched, and a loupe's nine rows (80 either
- side) fit inside it.
-- Unchanged: the source file, the frame chain, the allocations; for the
- stack's roles, the call frame information, the locals' places at each
- frame's pc, and the first stack pointer, as the last round asked.
+- For the map, as before: `--stack 1024`, `--disasm 69`, `--around 256`;
+ the source file, the frame chain, the allocations, the call frame
+ information, the locals' places, the first stack pointer.
+- **For a descent**, at every stop: the backtrace by the unwind tables (in
+ since this round, by the tracer's note; the build this round's mocks
+ were made with still lost `main` at the first instruction of `open`,
+ `#1 libc.so.6+27781`); for each frame the module, whether it has
+ source, its function's bounds, and three instructions round its call
+ row (the return address and the instruction before it); names at every
+ pc, the first instruction of a function too (`open`'s entry printed
+ bare, `7ffff7d10ec0`, where its middle printed `libc.so.6!open+261`);
+ a PLT stub by its symbol (`open@plt`, not `hello+1070`) and its GOT slot
+ (`open@got`) with the slot's value at the stop; whether the slot is
+ still lazy.
+- **For a crossing**, at the `syscall` row: the number and its name, the
+ arguments by the call's signature (a descriptor with what it is open
+ on, a path or a buffer with its bytes, flags by name), the result, the
+ registers it clobbered.
+- `ztrace record --by insn --from main` began in the loader with the
+ ReleaseFast build used here (`hello`, 120 moments, all in `ld.so`):
+ `--from` did not take; `dbg` with a breakpoint was used instead.
+- For the heap scene: see [the scene](motion.md#a-scene-libcs-heap-from-the-inside).
## Token changes
-Against `anim/src/theme.zig` as it is now (22:37): "In theme.zig" is what
-is in the file, "Is" what the documents say.
+Against `anim/src/theme.zig` as it is now (23:07): "In theme.zig" is what
+is in the file, "Is" what the documents say. The map's, the minimap's, the
+loupe's and the arc's tokens, the lift's colours, the clock's count at
+1648, and `metric.bytes` and `metric.slot`'s new columns are in, as asked.
| Token | In theme.zig | Is |
| --- | --- | --- |
-| `map` | none | `canvas` 3840 by 2160; sides 112, top 96; the stage 3616 by 1688; four columns of 880 at 112, 1024, 1936, 2848; the thread at 1008; the window outline 2 in `dim`, 4 out; panel lengths as listed |
-| `minimap` | none | at (1664, 912), 192 by 108, a twentieth of the map; strokes 1 high at 45% toward the page; marks at least 1.5; windows 1 in primary, 1.5 bright for the one in focus; frame 1 in `rule` |
-| `canvas.clock_count` | at the stage's right end | ranged right at 1648, left of the minimap |
-| `color.lift`, `lift_tag`, `shade` | none | `121c52`, `22317a`, `02061a` |
-| `metric.loupe` | none | 880 wide; 5 rows in the working frame, 9 on the map; hangs from the foot of its pointer's row, its left edge 92 left of the pointer's digits; shadow 12 and 16, a deeper one 20 and 26 and 120 to the right; stem 3 |
-| `time.loupe` | none | `read` 0.10; `stem` 0.30; `rise` 0.20, shadow 0.30; `frame` after 0.10; `close` 0.20 |
| `time.dive` | none | `bright` 0.10, `veil` 0.30, `move` 1.20 (`glide`, 0.10 between panels), `fade` 0.20 at its end, `still` 0.60; `surface` the same, the move first |
| `time.flash` | none | 0.20: a ring from 8 to 14 |
| `time.caption_max`, `first_step` | none | 12.00; 4.00, 5.00 when a scene opens on the map |
| `metric.span.name_max` | none | 300 |
-| `metric.arc` | none | lanes 4, 10, 16 (a dump, a loupe), 4 and 10 (the stack); out at 21, head 7 by 8 at 22; rows left at 9 and entered at 15 going up; stroke 2, radius 4; standing at 60% toward the page |
-| `metric.bytes.bracket`, `address`; `metric.slot.lane` | 7, 18; 10 | 24, 34 (the bytes 12 after the address, 132 at least); 16 |
-| `time.arc` | none | `draw` 0.20 from s+6; `fade` 0.20; `quiet` 0.40 with the cool; `lane` 0.20 |
| `metric.calls` small, folds | full only | disc 36, level 38, badge 24 at 6 and 32, mono 20; fold past 13 leaves or 6 levels |
+| `metric.width` | none | cells 5 by 10, 7 apart, `dim`, standing on the baseline 3 after the `]`; what follows 4 after the last cell; eight cells and a count past 8 bytes |
+| `metric.insn.wide` | none | 12 a digit past seven, per window: libc's mnemonic at 240, its annotation at 624 |
+| `metric.descent` | none | callers' windows 3 rows; a head a row (rule 2, name at 40 in Go Medium 18, what it is ranged right in Go 18); the call lane at x 14, 2 in primary, head 7 by 8 into the name; into the kernel 3 in vellum, its head in ink; three windows of code, then a fold row; the kernel's window a head and two rows |
+| `metric.node.two_rows`, `metric.bin` | none | rows 110 apart, nodes 136 wide; the bin box 160 by 44 at the row's left, its count on a 30 square on the shoulder; a free node's outline dashed 12 on 8 |
+| `time.descend` | none | `close` 0.20 then 0.30 (`glide`), `ring` 0.20, `lane` 0.30, `head` 0.20, `rows` 0.20 a row 0.03 apart, from 1.10 after the fire; the step 2.70 |
+| `time.cross` | none | the registers framed 0.10 apart from 0.30; `lane` 0.40 from 0.80; the kernel's window 0.20; the answer up 0.40; the step 3.60, 4.90 when it moves bytes |
+| `time.ascend` | none | `close` 0.20 a row, 0.03 apart, from 0.80; the lane back 0.20; the caller's window 0.30 (`glide`); the step 2.30 |
Unchanged and already there: the 1920 stage and its splits, the palette
with the marks of the last round (`wash`, `struck` `b54f42`, the corner),
@@ -1373,6 +1633,9 @@ camera's scales.
7. `call` spans; the three splits and `relayout`; the camera at x1.5.
8. The other lenses in the band.
9. The map and the minimap; `dive` and `surface`; the loupe.
+10. Operands without size words and `width`; the row's detail; the
+ `descent` and `descend`, `cross`, `ascend`; malloc's words; `nodes` in
+ two rows.
Export: