1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
|
# canim: the design language
This is the catalogue. Everything that can appear in a canim frame is a
**block** with a name, specified here once; everything larger is a
composition of blocks. The names are the ones the code uses. A gallery
scene that draws every block in every state is the test of this page.
- How blocks move is the [verbs](#6-verbs) below; the reasoning and the
full timing charts behind them are in [`motion.md`](motion.md).
- The blocks drawn: [`mock/`](mock). [Which mock shows which block](#the-mocks).
- The numbers are tokens in `anim/src/theme.zig`:
[what to change there](#token-changes).

## The rules
1. **Lapis page, vellum ink.** A deep blue page, cream text, gold for where
execution is, vermilion for what just changed.
2. **Ink says what a thing is; paper says what happened to it.** The colour
of a value's digits is where it points, or that it is a keyword or a
string. A fill, a frame, a turned corner is an event. The two never
share a channel.
3. **Every mark has its own form.** Written is filled, read is framed,
changed is ticked, freed is hollow, unknown is two dots. Nothing is told
by hue alone.
4. **Solid vellum is the kernel**, and nothing else.
5. **Panels are acme windows.** A tag, a 2-unit rule, a body. Square
corners, no shadows, no gradients, no glow.
6. **The whole context, always.** Every register followed as far as it
points, the instructions round the pc, the source, the stack: in
the same place in every frame, as pwndbg shows them. A lens (a list, a
tree, an array) is drawn over that state and never instead of it.
7. **Panes are views of one machine, and the ties are drawn.** A source
line and its instructions, a register and what it points at, a run of
bytes and the node drawn from them: each relation has a form, a route
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.
## Vocabulary
Six layers. A block is made only of blocks from the layers above it in
this table.
| Layer | Block | Is | Options and states |
| --- | --- | --- | --- |
| 1 atom | [`address`](#address) | hex digits in the ink of where they point | `lead`, `name`, `rwx` |
| | [`value`](#value) | anything that is not an address | by class: digit, number, negative, string, fd, flags, bool, char, unknown |
| | [`arrow`](#arrow) | the sign between two things in a chain | `points`, `holds`, `more` |
| | [`hop`](#arrow) | a `points` arrow and the address it leads to | |
| | [`byte`](#byte) | two hex digits of a dump | `number`, `pointer`, `text`, `loose`, `unread`; `pad` |
| | [`mark`](#mark) | what happened to a thing | `current`, `armed`, `struck`, `held`, `read`, `trail`, `allocated`, `freed`, `fault`, `attention`, `unknown`, `kernel` |
| | [`plaque`](#plaque) | a solid label under the current mark | `gold`, `chip` |
| | [`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` |
| 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 |
| | [`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 |
| | [`source`](#source) | a window on the file | 14, 8 or 10 lines |
| | [`disasm`](#disasm) | the instructions round the pc | 17 or 9 rows |
| | [`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 | |
| 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 |
| | [`echo`](#4-ties) | the same mark in two panels at once | for a step |
| 5 frame | [`stage`](#5-the-frame) | the working frame: the band and the two columns | split `none`, `beside`, `subject` |
| | [`map`](#the-map-and-the-minimap) | the working frame unfolded, every panel whole: 3840 by 2160 | the key |
| | [`minimap`](#the-map-and-the-minimap) | the map at a twentieth, in the working frame's corner | windows, marks, `flash` |
| | [`clock`](#clock-and-caption) | where in the recording | |
| | [`caption`](#clock-and-caption) | the narrator | |
| | [`veil`](#clock-and-caption) | page over what a beat does not touch, or a pace cannot show | |
| | [`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 | |
| | [`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 | |
## 0. Tokens
### Grid
**The working frame** is 1920 by 1080 units, at 60 frames a second; a 4K
master is two pixels a unit. It is where a scene is told, and everything
in it reads at 1080p. **The map** is 3840 by 2160 units at the same type
size: the working frame unfolded, every panel at its full length. It is
shown filling the frame (at half its size, so at 1080p its text is
texture), and small in the corner of the working frame as the
[`minimap`](#the-map-and-the-minimap). The working frame's panels are
windows onto the map's columns.
| Token | Value |
| --- | --- |
| context mono | 20: an advance of 12, rows of 24, in the working frame and on the map alike |
| panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides |
| between panels | 12 |
| columns | working frame: two of 880, at x 64 and 976; the gutter between them, 944 to 976, belongs to the ties. Map: four of 880, at x 112, 1024, 1936 and 2848, 32 apart |
| strokes | 2: rules, frames, chain arrows, a projection. 3: a link, the thread, a lens's frames, a loupe's stem |
### Colour
| | Hex | On page | Use |
| --- | --- | --- | --- |
| page | `0a1030` | | the ground; panel bodies |
| raised | `16245f` | 1.3 | tags, node bodies, the paper under a field's bytes, chips |
| well | `101a48` | | a node's pointer half |
| rule | `3a4a8a` | 2.2 | rules, quiet brackets |
| bright | `fff8e8` | 17.6 | titles, a set flag, the newest frame's name |
| primary | `eee6d2` | 14.9 | numbers, names of code, plain code |
| dim | `9aa6d9` | 7.8 | register names, `loose` bytes, notes |
| faint | `6a7ab8` | 4.5 | chain arrows, line numbers, a decimal beside its hex |
| ink | `050a24` | | letters on a solid mark |
| wash | `212644` | 1.2 | the current row's band: bright a tenth of the way over the page, opaque |
| lift | `121c52` | 1.2 | a loupe's surface; its tag `22317a` |
| shade | `02061a` | | a loupe's shadow, the one shadow there is |
**Regions: the ink of an address**, as pwndbg colours them. The legend is
the registers' tag, always on screen.
| Points into | Ink | On page | Also told by |
| --- | --- | --- | --- |
| stack | `f2d675` | 13.0 | by far the lightest |
| heap | `86b6ff` | 9.0 | |
| code | `ff8f9a` | 8.5 | its name always follows |
| data, writable | `d59cf5` | 8.8 | |
| writable and executable | its region's | | a 2-unit underline |
| read-only data | primary | 14.9 | |
| a string | `b5e8c8` | 13.6 | its quotes |
Known weakness: heap, data and code have one luminance, so between those
three the ink is hue alone, as it is in pwndbg. A code address has its
name; heap and data have only their digits.
**Marks: the colour of an event.** Solid, and the ember it cools to.
| Role | Solid | Ember |
| --- | --- | --- |
| current | gold `e8c46a`, on the plaque only; the row's band is `wash` | trail `ae9350`, `746235`, `463b20` |
| write | vermilion `ff6a4a`, for the arm, the turned corner, a projection; a strike's paper `b54f42` (vermilion 70% over the page), its digits bright | `5a2218` |
| read | `6fd6e6` | `1c4652` |
| allocated | `7fdc9a` | `1f4a33` |
| kernel | vellum `eee6d2` | |
**Code**: plain primary; keyword and mnemonic `c0dcff` bold; string and
number `b5e8c8`; comment dim italic. **Pigments** name an object across
views, at most four: ochre `8a5e0c`, teal `17707c`, madder `a03060`,
malachite `1c7450`, violet `6a3fb0`, azurite `2f5fc4`. Never a ground
under region ink.
### Type
| Face | For |
| --- | --- |
| JetBrains Mono NL Medium | all mono under 30 |
| JetBrains Mono NL Regular | mono at 30 and over |
| JetBrains Mono NL Bold | keywords, mnemonics, a struck value, plaques, pins |
| JetBrains Mono NL Italic | comments |
| Go, Go Medium, Go Bold | captions and notes; tags; titles |
NL because the plain family's ligatures turn `->` into a sign that is not
in the source. Medium because thin strokes on a dark ground die first in a
stream. OFL and BSD; `/usr/share/fonts/TTF/`, `/usr/share/fonts/go/`.
| Mono | Advance | For |
| --- | --- | --- |
| **20** | 12 | the context, the dumps, a loupe, the map |
| 25 | 15 | a lens's values beside; its labels and pins as subject |
| 30 | 18 | the context under the camera at x1.5 |
| 35 | 21 | code inside a caption |
| 45 | 27 | a subject lens's values; a value in flight |
| 60 | 36 | a title card |
Sans: 18 notes and legends, 20 tags, 40 on 54 the caption, 44 and 116 a
card. **Floor: mono 20, sans 18.** At 480p no digit at 20 can be trusted,
so: **nothing the narration depends on is only at 20.** It is also in the
caption at 35, or the camera goes to it. On the map, filling a 1080p
frame, mono 20 is 10 pixels: texture, which the caption carries; in a 4K
export it is 20 pixels and reads.
## 1. Atoms
### address
Lower-case hex, **unbroken**, as long as it is, no `0x`, no leading zeros:
`28b41090`, `7ffe970f17b0`, `1001926`. Its ink is its region.
| Option | Draws |
| --- | --- |
| `lead` n | the first n digits at 60% of the ink toward the page. Used in a column of addresses (disassembly, stack slots, a dump's gutter) with n = the digits every row shares, leaving at least two: the eye reads the part that changes |
| `name` | code only: `name+offset` in primary, 10 units on; the module when there is no symbol, its offset from the module's first mapping: `libc+27781` |
| `rwx` | a 2-unit underline |
States: plain; `struck` (bold, in ink, on solid vermilion 5 wider each
side); `read` (a 2-unit frame, 6 out); `held` (a turned corner at its top left). Data:
a word and the mapping it lies in. Mocks 9 to 11, everywhere.
### value
What is not an address. The tracer classifies; the class decides.
| Class | Because | Shown |
| --- | --- | --- |
| digit | under 10 | `4` |
| small number | 10 to 0xffff | hex, and its decimal after it, faint: `0x21 33` |
| large number | larger, not in a mapping | `0x` and its hex, unbroken, primary |
| small negative | within 4096 of 2^64 | `-1` |
| string | a pointer to printable bytes and a NUL | `"..."` in string ink, C's escapes; cut with `…` and no closing quote, never under six characters |
| file descriptor | a signature or a type says so | the number, and faint what it is open on: `3 "note"` |
| flags | eflags; an argument a signature calls flags | names; bits no name covers as `0x` and their hex: `O_RDONLY 0x8000`. Never bare hex |
| boolean, character | the debug info types it so | `true`; `0x41 'A'` |
| unknown | never observed | two dots |
A typed value follows its type: an `int` is decimal alone, a pointer an
address alone. Mocks 9 to 11 show digit, small number, string; the rest
are not drawn.
### arrow
30 wide: a 2-unit shaft and a head 8 by 10, faint.
| Kind | Reads | pwndbg |
| --- | --- | --- |
| `points` | which points to | `—▸` |
| `holds` | which holds (what follows is not an address) | `◂—` |
| `more` | and goes on: `points` and three 3-unit dots | |
A **hop** is a `points` arrow and the address after it: the unit a chain
is counted, cut and re-followed in.
### byte
Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth.
| Kind | Ink | Paper |
| --- | --- | --- |
| `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 |
| `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 |
`unread` is about the stop shown, not the recording: memory the
recording watches (the stack it records, a heap it tracks) is known from
its last observation; memory it does not watch is known only where that
stop read it ([`seen`](#hexdump)), and an older stop's bytes there are
drawn as unread, since they may be out of date.
`pad`: in a number stored low byte first, the bytes above its highest
non-zero byte are at 45% toward the page: `70 10 b4 28` stands out of
`00 00 00 00`, and is the address `28b41070` read from the right; stored
high byte first (`big`), the zero bytes before its first non-zero one:
`00 03`. A mark covers the bytes whose value changed, never more: see
[`bytes`](#bytes). Mocks 9 to 11, 13 and 14.
### mark
What happened, on paper and never in the letters.
| State | In the context (mono 20) | In a lens's cell |
| --- | --- | --- |
| `current` | a gold plaque on the label, and across the row a white wash (`wash`) | the same |
| `armed` | a 2-unit vermilion frame, the old value still in it | 3 units |
| `struck` | the softened vermilion (`b54f42`) behind the value, 5 out each side; digits bold, bright | the same, the cell's fill |
| `held` | a turned corner: a vermilion triangle 9 on its sides at the value's top left, for three steps | the same at the cell's top left, 12 |
| `read` | a 2-unit frame in read's colour, no fill | 2 units, 2 out |
| `trail` | a 4-unit bar at the row's left edge: three tones, newest first | |
| `allocated` | | ember block in a solid frame |
| `freed` | | hollow, dashed 12 on 8 off, hatched |
| `fault` | hazard bands round an ink plaque naming it | the same |
| `attention` | a 2-unit bright frame | 3 units; a veil on the rest |
| `unknown` | two dots | two dots |
| `kernel` | the ground is solid vellum | the same |
One gold mark a panel. One step's writes in vermilion at a time. Gold is
kept for the plaque, the pc's marker, rip's name, the thread and the
trail: where execution is, as a sign and not as a band.
The first videos drew `current` as a gold ember across the row, `struck`
as solid vermilion with ink digits, and `held` as a tick left of the
value: the band was the strongest thing in a dense frame, the solid strike
glared, and the tick read as a text cursor. [Mock 15](mock/15-marks.png)
sets those (A) beside these (B) and a whiter reading (C: a white plaque, a
white strike framed in vermilion, a bar under the held value) on the same
rows. Mocks 9 to 18 show current, struck, held, read, trail, unknown; 1 to
8 the rest.
### plaque
A solid label. `gold`: behind the label of a current row, letters bold in
ink (rip's name, 54 wide; a line number, 50; the pc's marker, 24, with an
ink triangle). `chip`: raised, 32 by 20, behind a set flag, letters bold
and bright. Nothing else is a plaque: a register's name at a target is a
[`pin`](#pin).
### pin
A name at the thing it points to, and a head in the target's region ink
that touches the target. A register's name is bold primary; a variable's
(a pointer the debug info names: `cur`, `head`) is bold in the ink of
where it lives, stack for a local and data for a global, so `cur` under
a heap node reads "on the stack, pointing here". It answers "who points
here", and it is a [`link`](#4-ties) at rest.
| Form | Where | Anatomy |
| --- | --- | --- |
| `row` | a row's lane (the stack) | the names, then a head 9 by 12 pointing right at the row's address |
| `under` | under a drawn node or cell | a stub 3 wide rising to the node's bottom edge, head 10 by 10; names 9 either side of the stub |
A pin for every register whose value is exactly the row's or node's
address, and for every variable the scene names, from the opening; three
names, then a count. No box, no fill.
- **Names keep their side.** On an `under` pin the first name to come is
left of the stub and the next right of it. When one leaves, the others
stay where they are, and the next to come takes the free side. Two names
never print in one place.
- **Names keep their order.** On a `row` pin the names are in pwndbg's
order of the registers (`rbp rsp`), variables after them. A name that
comes takes its place in that order and the others slide aside for it
(12 f, `standard`) before it lands; one that goes leaves, and the others
close up after (12 f). A travelling `rsp` is the same pin on every row
it passes.
- **A pin is one thing.** One register or variable has one pin, and it
travels between the things it points at: it never jumps, and is never
in two places ([`travel`](#6-verbs)).
Mocks 9 to 12.
### bracket
A span marked at its edge: a stroke down the span and a serif at each end,
toward the span. `quiet`: 2 units, serifs 5 (a node's row in a dump, at
60% of its region's ink; an older call frame, in rule). `tie`: 3 units,
serifs 6 or 7, in the ink of the tie it ends.
### tag
24 high, raised. A 12-unit box 8 in: solid gold where the narration is
(`focus`), a faint 2-unit outline elsewhere. The title, Go Medium 20,
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).
## 2. Rows
Every row is 24 high and one line. None wraps; what does not fit is cut at
its far end and says so.
### chain
`address (points address)* (holds value)?`
- A code address ends a chain with its name. A string ends it in quotes.
- **Depth** is the recording's. **Cut** where the row's `room` ends: a
string is shortened first, then the chain ends early in `more`. Nothing
is taken from the middle.
- **Marks** are per hop. If the first is struck the register was written
and the rest are followed again ([`extend`](#6-verbs)); if a later one,
memory changed under a pointer that did not, and the turned corner sits on
that hop alone.
- No lines to targets. Thirty chains would be a net; a chain is tied to
its target by ink, by digits, and by the target's pin.
### reg
A name (dim) 12 in; its chain from 72; room to 12 from the edge.
`rip`: gold plaque on the name, the wash across, the address in code's ink
and its name. Never struck. Its row carries **flags** at the right end:
eight names on a pitch of 42. Set: upper case on a chip. Clear: lower
case, dim. Changed: a turned corner. (The value `0x206` is not drawn: the names are
the value.)
### slot
A word of the stack, pwndbg's way and a little more.
| x | Column | |
| --- | --- | --- |
| 4, 10 | arcs | the [`arc`](#arc) lanes: a word holding the address of another slot in the window |
| 16 | pins | the `row` pin's lane, to 112: every register whose value is this word's address |
| 172 | offset | from rsp, hex, `+18`, faint, ranged right in four characters (`-8` above rsp) |
| 184 | address | stack ink, `lead`; then the chain, its first hop the word's content |
| right | role | what the word is, where the recording knows it, ranged right where the chain's room ends: `saved rbp`, `saved rbx` (dim); a local's name (primary); at the process's start `argc`, `argv[0]`, `argv end`, `envp end`, `auxv` (dim) |
| 14 from the right | span | the [`call`](#call) bracket, its name left of it |
A return address needs no word: its chain is code, named (`10018b0
main+80`), and its frame's bracket ends on it. Room runs out from the
right: a span's name is never cut, a role is never cut, and the chain on
the rows they sit on ends 12 before them, cut by its own rule
(`sqlite3BtreeInsert` beside `7fffffffe980 → 7fffffffeb90 → …`).
`free`: a word above rsp, which the stack has not reached. Shown only
while the window is held still for the camera ([`visit`](#6-verbs)): its
address at 60%, its word in faint, no chain, no pin. A push fills it.
### insn
An instruction, pwndbg's way: what it is, and what its operands are now.
| x | Column | |
| --- | --- | --- |
| 2 | mark | a gold plaque 24 wide (current) or a trail bar 4 wide (ran) |
| 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 |
| 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 |
**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
a faint `…`. A cut that would fall inside `[]` falls before the `[`,
and the annotation's first hop is the address the brackets named.
| State | Draws |
| --- | --- |
| `current` | plaque, the wash across; annotation in full ink |
| `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 |
**The annotation**, by what the instruction does:
| It | Annotation |
| --- | --- |
| 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 |
| 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 |
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.
### 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.
**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
six. Everything right of the column moves by the extra (12 a digit), the
gold plaque widens by as much (50 + 12 a digit), and the text loses as
many characters (64 for six digits). The width is the program's, not the
window's, so a scroll across 99 999 does not shift the text. The
disassembly's `line` column follows the same width (see [`insn`](#insn)).
Mocks 13 and 14.
### bytes
A hexdump row. Its runs come from the types of what the program's
pointers reach: a run is one field of the element's type, an `int` 4
bytes and a pointer 8, never two fields and never a store's width.
| x | Column | |
| --- | --- | --- |
| 4, 10, 16 | arcs | the [`arc`](#arc) lanes: pointers to rows of the same dump |
| 24 | bracket | `quiet`, on a row that holds a drawn thing; `tie` when a projection ends here |
| 34 | address | region ink, `lead`; at 60% on a row that holds no drawn thing |
| 132 | sixteen `byte`s | on a pitch of 30, 12 more after the eighth |
| 640 | reading | what the runs read as, left to right, a character apart: a number in decimal (in its byte order); a pointer as `points` and its `address`, `NULL` dim; text in quotes, C's escapes, in a string's ink; a run left to the eye, or `loose`, as nothing; the chunk's size word before an allocation as a note in Go 18, faint (`malloc's: a chunk of 32`). Cut at the panel's edge with a faint `…` |
**Wide address.** The bytes begin 12 after the address ends, and at 132
at least: an address of up to seven digits leaves them at 132; the stack's
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.
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,
not a table: a page header's five numbers would not fit a pitch of three
characters, so no reading is ranged in a column, and two rows' readings
need not line up.
Marks: `struck` (the paper solid vermilion, digits bold in ink) covers
the bytes whose value changed between the two stops, inside one run,
from the first that changed to the last: a pointer whose low byte alone
moved is struck on that byte, and two `int`s swapped are struck as two
runs of 4. A byte stored with its own value is not marked: the recording
sees values, not stores. `read` (a 2-unit frame 3 out) frames the run
read. `held` is a turned corner at the top left of what was struck. A struct wider
than a row spans rows, and its bracket spans them.
### call
One frame of the call chain, in two forms.
- `span`, on the stack: a bracket 14 in from the panel's right edge down
the slots that are the frame, and left of it the function's name, Go
Medium 18; for the function a `calls` lens draws, its arguments as a
call, `fib(4)`: two frames of one function are told apart, and the
digits are the ones on its node. The name is whole up to 300 units
(`sqlite3PagerCommitPhaseOne`, 26 characters, is 240), then cut with
`…`; the chains beside it make room ([`slot`](#slot)).
`newest`: gold bracket, bright name. Older: rule and dim. A frame that
runs past the window has no serif at that end.
- `row`, in a backtrace panel: `#n` at 12 (a gold plaque 40 wide on the
newest), the name and offset in primary at 60, the arguments at 384
(`n=4`, primary), file and line ranged right, dim. Arguments where the
debug info gives them.
### arc
A pointer whose target is a row of the same panel is drawn, not only read:
an arc from the pointer's row to the row it names, in lanes at the
panel's left edge. It is the disassembly's jump lane given to data, in
every panel of rows that holds pointers: a dump (the band's view,
`memory`), a [`loupe`](#loupe), the stack.
| Part | Drawn |
| --- | --- |
| lanes | a dump and a loupe: three, at 4, 10 and 16 from the panel's left edge (the quiet bracket moves to 24, the address to 34, the bytes 12 after it, 132 at least). The stack: two, at 4 and 10 (the pins start at 16) |
| arc | 2 units, corners of radius 4, in the ink of the region pointed into: out of the pointer's row at its left (x 21), along its lane, into the target's row at its left, head 7 by 8 at x 22, before the bracket and the address. Going up it leaves its row 9 down and arrives 15 down (going down, 15 and 9), so a chain of pointers (1004090 → 1004070 → 1004050) runs in one lane without touching |
| ink | standing: 60% toward the page. Full: in the step that writes or reads the pointer, and always in a loupe, which was opened to show them |
| a target mid-row | the head on its row; the `read` or strike on the target's own bytes says which |
**Nesting.** Overlapping spans take separate lanes, the longest outermost;
spans that do not overlap share one. Nested arcs never cross; interleaved
ones cross once, as jump arrows do. Three lanes (two in the stack) is the
most a panel holds before it is noise: past them the arcs of the step come
first, then the shorter; the rest are only read, and nothing is hidden,
since every pointer's reading names its target.
**Out of the window.** A pointer whose target row is in the same region
but not shown: in the step that writes or reads it, a stub along its lane
to the panel's rule, head on the rule; otherwise nothing. No count, unlike
a link's stub: the lane has no room for one, the reading names the
address, and the minimap shows where.
**Which form carries a pointer**, when more than one could:
- **In a panel**, between its own rows: the arc. The stack's frame chain
(a saved rbp) is the exception: the `call` spans already draw the frames
it makes, so its arc is drawn only in a step that writes or reads it.
- **A loupe** carries the arcs among its own rows; a dump showing the same
rows withholds them while it is open (one place, the one opened for it).
A loupe's stem already ties the pointer it opened from; a loupe never
opens for a target its own rows hold.
- **The lens's drawing** draws the same pointer as its arrow (a node's
`next`); the view's arc is that pointer's bytes. Both stand: they are
the idea and the machine, tied by ink and digits, and a step that turns
the pointer turns the arc at the memory level and the arrow at the idea's.
- **A flat chain** (a register's, a stack word's) whose hop lands on a row
of another panel: its `pin` where that panel has a pin lane (the stack,
a node); otherwise ink and digits. In the step that sets it, a `link`.
No standing line across panels: an echo of the target's row whenever the
pointer's row is current would flicker on every step.
Its motion is under [`arc`'s verbs](#6-verbs). Mocks 9 to 11, 19, 21.
## 3. Panels
A panel is a tag and rows. Its rows never reorder and none is hidden to
make room.
### registers
Seventeen `reg`s in pwndbg's order: rax rbx rcx rdx rsi rdi rbp rsp, r8
to r15, rip (with the flags). Tag: the region legend. 440 high. Reads the
moment's registers and mappings.
### stack
`slot`s from rsp, low addresses on top: eight; six when the lens is the
subject. `call` spans down its right edge for every frame in view: the
backtrace, drawn on the words that are each frame. rsp and rbp are pins
in its lane. Reads the stack words, each frame's extent (the
frame-pointer chain, or the unwinder's CFA), and for the roles the saved
registers (the frame-pointer chain; the call frame information for the
prologue's pushes), the locals' names and places (the debug info at the
pc), and the first stack pointer (argc, argv, envp, auxv).
**The window** is on the newest frame: the words from rsp to its return
address, `[rsp, rbp+16)`. It is a window onto the map's stack column, which
runs from 16 words above rsp to the stack's top.
- Where the frame is no longer than the window, the window's top is rsp
and the caller's words fill the rest.
- Where it is longer, the window scrolls down it by whole slots
([`scroll`](#6-verbs)) to keep the slot a step touches in its middle
rows (the third and fourth of six; third to sixth of eight), and stays
there until a step touches a slot outside them. Its top never passes
above rsp.
- A push or a call moves the top with rsp: the rows slide one slot (18 f,
as rows making room), at the memory level, before the new word is
armed. A window going farther than its height fades through instead
([`scroll`](#6-verbs)).
- While the camera is on the stack the window holds still
([`visit`](#6-verbs)): pushes fill `free` slots in the middle of the
frame, and rsp's pin climbs to them.
Tag: `six words from rsp`, or the range when scrolled (`rsp+20 to
rsp+48`), and `· the frames they belong to`.
### backtrace
`call` rows, newest on top. 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.
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
stops share, counted from the oldest, slide to their new depth (24 f,
`glide`), their numbers changing at the middle of the slide; then the new
frames fade in (12 f), newest last. A frame's `#n` is its depth, not its
identity: the slide is what says it is the same frame.
### source
A window on the whole file, scrolled by whole lines to keep the current
line in its middle third. Fourteen lines; eight beside a lens (the loop
in hand); ten when the lens is the subject. Tag: the file, and `lines 19
to 26 of 42`. A line farther than a window away (another function in a
file of 262 899 lines) is not scrolled to: the window fades through
([`scroll`](#6-verbs)). Line numbers are as wide as the program's
largest ([`line`](#line)). On the map the file is whole, or 69 lines round
the current one when it is longer.
### disasm
Seventeen `insn`s in address order: the pc's, eight above, eight below.
Nine (four, the pc, four) when the lens is the subject.
- Rows above the pc are the function's own instructions where it has
them; near its start the window stays full from below.
- Rows of another function are `outside`: plain, under a rule and its
name.
- The rows that ran in the last three steps are `ran`, above or below the
pc: with the jump lane they show how control came here.
- Tag: the function's name.
On the map the column is 69 rows: the function whole when it fits, with
its neighbours round it.
### lenses
A lens is the band across the top of the stage: **a drawing, over the
program column, and over the state column the pane the drawing is a view
of**, each a panel with its own tag. The gutter between them is the ties',
as it is below. Beside the context both are 152 high; as the subject the
drawing is 296 and its view 200 ([the frame](#5-the-frame)). On the map
the drawing keeps its subject size and the view is its region whole.
| Lens | Drawing | Its view | Mock |
| --- | --- | --- | --- |
| `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 |
| `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 |
`memory`, on the map, is the column of the regions the scene's steps
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.
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
is not a `relayout`: the backtrace gives way to the kernel's side when the
row reaches `pwrite64`.
**What a new lens must provide** to fit the frame:
1. A drawing that fits 856 by 116 (`beside`) and by 260 (`subject`).
2. Its view, a pane of rows that fits the state column (five beside,
seven as subject; the region whole on the map), and for every element
the bytes, slot or register it is drawn from.
3. A `place` for every element, so ties can land. A 12-unit lane clear at
the top of the drawing and one at the bottom: **bytes from its view
arrive from above; pointers, and a frame from the stack, from below.**
4. Each mark on its cells: `current`, `armed`, `struck`, `held`, `read`.
5. Its `establish`: how its elements come in beside what they are drawn
from.
### nodes
Boxes of 116 by 44, 28 apart: six fit the drawing (124 by 72, 22 apart,
as subject). The value's half is raised, the number in mono 25 (45); the
pointer's half, 48 wide, is the well, with a 10-unit square the arrow leaves from. Arrows
3 wide in the ink of the region pointed into, head 12 by 10; null is a
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.
### hexdump
`bytes` rows, sixteen a row, a window of the region kept round the rows
the step touches: five beside, seven as subject, five in a
[`loupe`](#loupe), the region whole (to 32 rows round what the step
touched) on the map. Rows in address order.
Tag: `its bytes`, then what the bytes are and where (`the heap, 28b41050
to 28b410bf`; `pBuf: page 2 of t.db, at rsi`), and the legend of runs:
each field's name in its bytes' ink, `malloc's`, `never read`.
Its runs come one of two ways.
- **Typed**: from the types of what the program's pointers reach, as the
`nodes` and `array` lenses have them: a field of a struct, an element
of an array, the allocator's words between.
- **`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`,
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
meaning is the file's and not the C's (an SQLite page).
**`more`.** Rows that hold no field (a dump by `fields`), or a gap in the
addresses (a typed one), are one row: at the address column, `more`'s
arrow and three dots, then the count of rows it stands for in faint mono
20: `→ … 253 rows`. When the rows that hold fields are more than the
window, the window is kept round the rows the step or the caption is on,
and the field rows left out are `more` rows too, with their count: never
cut off at the panel's edge.
**What a stop saw.** `seen`: of memory nothing watches, the part the stop
shown read (a debugger reads 32 bytes where a pointer leads); the rest is
`unread`, whatever an older stop saw there. `given`: the bytes a system
call was handed or filled, from the recording's capture of the call, as
the kernel took them. They come in over what the stop saw while the
kernel's work runs: dots to digits, 12 f, no strike (a value that was
always there, now known), the run framed as read while the kernel takes
it; at the next stop the program's own memory is shown again.
**Marks** are for changes the viewer could have seen: a dump that comes
in after the step that changed it, or a window that faded to a new place
([`continue`](#6-verbs)), arrives with its values plain.
### array
Cells in a row, an element a cell (80 by 44 beside, 96 by 72 as subject),
the index over each in faint, the variables that index it (`i`, `j`) as
`under` pins. Its dump's runs are its element's type. A swap is two
flights: each value lifts as a card (1.12 of the cell, 6 units off it),
one flies over and one under, on an arc a quarter as high as it is long,
34 at least and 120 at most, and never past the drawing's lanes: an arc
that does not fit is lowered until it does. In flight a card is over the
cells and under every name and pin, which stay legible through it.
### calls
The calls of one function as a tree under its caller, laid out for the
whole run so that a node is where it will always be from the moment it
appears: leaves in call order, a parent over the middle of its children.
| Part | Drawn |
| --- | --- |
| node | a disc 48 across; its argument in mono 25 at its centre, primary |
| levels | 46 apart, the root's centre 48 under the tag; leaves spread over the drawing's width (about 111 apart for eight) |
| result | on its shoulder (12 right of the centre, 42 up): a square of 30 framed 2 in faint, the number in mono 25 primary; struck when the call returns |
| edge | 3 wide, centre to centre, under the nodes; primary on the path of calls waiting, rule elsewhere |
| the caller | `main`, a raised box 64 by 28 left of the root on its level, the name in mono 20; an edge into the root |
States, as marks: `current` (the call running) is a gold disc, its
argument bold in ink; waiting (it called, and waits) a page disc in a
3-unit primary ring; done a raised disc; not yet made, nothing. The
caller is a node too: gold until the first call, then waiting. So the
band is never empty: before the first call it holds the caller, gold,
with the backtrace beside it.
Its view is the [`backtrace`](#backtrace): the waiting path read as rows,
`#0` the gold node. Each node is also the `call` span of its frame on the
stack, and the two are tied twice: by digits (`fib(4)` beside the span,
`4` on the node) and, on the step that makes or ends the call, by a
[`projection`](#4-ties) from the frame's return address to the node.
**A larger tree.** The leaves share the drawing's width less the caller's
box: about 680 units between the first leaf's centre and the last's. A
leaf needs its disc and the result on its shoulder, and 6 between: 72 at
full size (24 left of its centre, 42 right), 54 small (18 left, 30
right).
| The run's tree | Drawn |
| --- | --- |
| up to 10 leaves, 5 levels (fib(5): 8 and 5) | full: discs 48, levels 46, badge 30 at 12 right and 42 up, mono 25 |
| up to 13 leaves, 6 levels (fib(6): 13 and 6) | small: discs 36, levels 38, the root's centre 60 under the tag, badge 24 at 6 right and 32 up, argument and result in mono 20 (the floor), edges 3 |
| more | small, and folded: when a call returns and the tree laid out for the whole run would need more than 13 leaves or 6 levels, finished subtrees fold, deepest first, until it fits |
A **fold** is a finished call standing for its whole subtree: a done disc
with its result on its shoulder and under it, faint mono 20, how many
calls it hides, `+12`. It folds 18 f after its result is struck: its
children glide into it (18 f, `glide`), then the tree is laid out again
with it as a leaf and every node that moves glides to its new place (18
f). A path deeper than six levels keeps its top three and its newest
three, the levels between drawn as one dashed edge (12 on 8) with the
count of calls on it, `… 9 calls`. Both are `more` for a tree: what is
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`.
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:
- 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
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.
- 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.
### loupe
The telescope's other form. A `chain` on a row says, flat, `rdi →
1004070 ◂ 9`; a **loupe** opens the place it points to: a panel floating
over the context with the memory round the target, the pointed thing
framed, read by its type where the recording has one. A pointer in it can
open the next, and a chain becomes panels in depth.
| Part | Drawn |
| --- | --- |
| panel | 880 wide, a tag and five `bytes` rows (152 high): the target's row in the middle, two before and two after (80 bytes), its runs typed (a node's value and next, malloc's words) or by `fields`. On the map it has nine rows (144 bytes), as everything there is longer |
| tag | `rdi → 1004070`, mono 20, the pointer it opens from and the target in its region's ink; ranged right, the region and the type, `heap · struct node, 16 bytes`, Go 18 dim |
| target | its run or its struct framed as `attention`: 2 units, bright |
| lift | its surface `lift` (`121c52`), its tag `22317a`, a 2-unit `dim` frame, and under it a solid shadow (`shade`) 12 right and 16 down; a loupe opened from a loupe, 20 and 26. This is the one place in canim with elevation: a loupe is not a panel of the frame but held over it |
| stem | the tie from the pointer to the loupe: a `link` (3 units, the target's region ink, head 10 on the loupe's tag), leaving the pointer where its row has room after the chain, or from a 3-unit bracket under a pointer inside a loupe |
**Where it floats.** In the working frame it hangs from its pointer: its
tag's top on the foot of the pointer's row, its left edge 92 left of the
pointer's digits (so the tag's address sits under them), clamped to the
stage, and a 4-unit bracket under the digits lying on the tag: the stem,
as short as a stem can be; it covers the rows under its pointer, whole. A loupe opened from a loupe hangs the same
way from its field, 120 to the right, over the older one's lower rows. It never covers its own pointer, the current marks
(the pc's row, the current line, rip's row), the ends of a drawn tie, or a
row the step changes; where the first place would, it moves down past
them, then to the other side; it stays inside the stage. On the map it is
a panel of its own beside the memory it shows (the map has room), and on
the minimap a lifted box there, its target's row outlined in its region's
ink.
**How many.** Two at most. A third, followed from the second, closes the
first as it opens, so a chain of any length is walked two loupes at a
time. While two are open their stems are two of the frame's three lines
(the thread is the third): that step draws no other link and no
projection.
**When the flat chain is right.** Always, as the standing form: every
register, slot and annotation keeps its chain, and a loupe never replaces
one. A loupe opens on a beat the narration names (a pointer followed, a
struct handed to a call) for a step or two; not at a run or a sprint; not
where the recording holds less than its nine rows round the target. It
opens and closes by its verbs ([`open`, `close`](#6-verbs)). Mocks 19 and 21.
## 4. Ties
The panes are one machine at different levels. A tie says which thing in
one pane a thing in another is.
| Tie | Says | Between | When | Form |
| --- | --- | --- | --- | --- |
| `thread` | this line is these instructions, and the machine is here | the source's current line; every run of its instructions in the disassembly | standing; moves with the current mark | gold, 3 units: a `tie` bracket on the line, one on each run, a line in the left margin (x 54) between them. On the map, where source and disassembly are side by side, across their gutter (x 1008) |
| `link` | this register now points at that | the `reg` just struck; the row or node whose address it holds | for the step that set it | 3 units, in the ink of the region pointed into, head on the target; ends in the target's `pin` and leaves it behind |
| `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; or the return address of a frame made or ended, on the stack; the part of the drawing made of them (a node's address, a cell, a call's node) | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket at the part (over a node's address; under a call's node); and the mark itself on the run and on the part |
| `echo` | these are one event | the same mark at the same instant in two panels: the annotation's address and the dump's run | for that step | no line |
| ink, digits | these are one thing | an address anywhere and its row, node or name; a call's arguments on its span, its backtrace row and its node | always | no line |
`call` spans and `pin`s are ties too, the kind that need no line because
they sit on their target.
The calls lens needed no fifth tie: a frame's return address is the
bytes the call left in memory, and the node is the part of the drawing
made of them, which is what a projection says. A node and its frame are
also tied by digits, standing, through the arguments on the span.
**Budget.** One `thread`, always. For a step, one `link` and one
`projection`, or the stems of two [`loupe`s](#loupe) (a stem is a link).
Never more than three drawn lines in the frame; a second pointer or a
second run in the same step gets `echo` and pins. rsp never takes a link:
its pin is on the window's top row by construction.
[`establish`](#6-verbs) draws no lines.
**Off the window.** A link whose target is outside its panel's window (a
slot past the stack's last row) comes down its lane to the panel's
nearest row, turns into the pin lane and ends on the panel's rule: a
head 9 by 12 pointing out of the panel, and beside it in faint mono 20
how far the target is, `12 rows`. The pin is drawn when the window
reaches it.
**Routes.** A tie runs only in channels, with corners of radius 8 (6 for a
projection):
| Channel | Carries |
| --- | --- |
| the left margin, x 54 | the thread |
| the gutter's left lane, x 950 | what climbs into the band from the state column: a link from a register to a pin under a node; a projection from a frame's return address to its call node |
| the gutter's right lane, x 962 | what keeps to its own height or goes down: a projection from the band's view to the drawing; a link from a register down to a slot |
| 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 |
| 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
below; the view's projections keep to the band in the right lane and
arrive from above. A link down to a slot takes the right lane under the
band and ends above the frame's return address, where a calls
projection leaves for the left lane: so the ties of one step cannot
cross. A tie may cross a panel's rule; it never crosses a letter, a digit
or another tie. A projection climbing to a call node crosses no edge:
under a node that has just been made there is only room for its own
children. The map draws the thread and no other tie: a link or a
projection is a step's, and steps are told in the working frame.
**Order.** A tie arrives before the thing it points to reacts: see
[`link` and `project`](#6-verbs). Mock 9 shows the standing ties; 10 and
11 all four; 12 the projection to a call; 21 a loupe's stem.
## 5. The frame
The working frame: where a scene is told.
| Band | y | |
| --- | --- | --- |
| margin | 0 to 48 | page |
| stage | 48 to 888 | 840: the lens band and the two columns |
| clock | 898 to 902 | |
| caption | 912 to 1032; the minimap at its right end, 1664 to 1856 by 912 to 1020 | |
| margin | 1032 to 1080 | page |
No data below 888 but the minimap, which the narration never depends on:
a player's controls may cover its foot.
**The program column** (left): source over disassembly: what was written,
what runs. **The state column** (right): registers over stack: what they
act on. **The lens band** (top): what it means, over the program column,
and the pane that means it, over the state column. The split is the one
thing about the layout a scene chooses.
| Split | Drawing | Its view | Source | Disassembly | Registers | Stack | Backtrace |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `none` | | | 14 lines, 48 to 416 | 17, 428 to 868 | 48 to 488 | 8, 500 to 724 | 4, 736 to 864 |
| `beside` | 152, 48 to 200 | 152, 48 to 200: 5 rows | 8 lines, 212 to 436 | 17, 448 to 888 | 212 to 652 | 8, 664 to 888 | in the stack |
| `subject` | 296, 48 to 344 | 200, 48 to 248: 7 rows | 10 lines, 356 to 628 | 9, 640 to 888 | 260 to 700 | 6, 712 to 888 | in the stack; the view of `calls` |
Each panel is a window onto a column of the [map](#the-map-and-the-minimap),
and the minimap shows where. **What gave** for seventeen instructions: a
lens, the whole of a function and seventeen instructions do not fit one
column of 840. So the lens left the program column for a band of its own;
the backtrace became spans on the stack; the flags moved into rip's row;
a panel's padding went from 6 to 4; and beside a lens the source shows
eight lines. As the subject the drawing takes eight rows from the
disassembly, the source gets two back, and the view stops two rows short
of the drawing so that the stack keeps six slots. With a lens open the
source is a window of eight or ten lines on the file: the map holds the
rest, and the minimap shows it.
| Of the frame | `none` | `beside` | `subject` |
| --- | --- | --- | --- |
| context | 68% | 56% | 48% |
| lens band (the drawing and its view) | | 13% | 21% |
| caption band, with the minimap | 10% | 10% | 10% |
### The map and the minimap
**The map** is the working frame unfolded: every panel at its full length,
on a stage of 3840 by 2160 units (sides 112, top 96, the stage 3616 by
1688), at the context's type size. It is one picture of the program at a
moment: the whole of a short file, the function round the pc and its
neighbours, all seventeen registers, the whole backtrace, the stack from
16 words above rsp to its top, the regions the scene's steps touch, the
lens's drawing, and the loupes open.
- **Columns by content.** Four columns of 880, 32 apart, in the working
frame's order: the drawing and the program's panels in the first two,
the state's in the last two. Panels are packed: each as long as its
content (a file of 42 lines is 42 rows, a backtrace of five frames five),
the next under it with 12 between; a panel longer than what is left of
its column continues at the top of the next column's free space, as a
second column of itself under the same tag, `continued`. Nothing is
stretched and nothing is centred to fill: a column's foot that is left
holds the map's key (the scene, the moment, the marks' legend), or is
page.
- **Its lengths.** The source: the file whole, or 69 lines round the
current line. The disassembly: 69 rows, the function whole where it
fits. The stack: from 16 words above rsp (the 128 bytes the recording
keeps under it) to the stack's top, folded into `more` after the
process's start. Memory: each region the scene touches, 32 rows round
what was touched, fieldless rows folded. The drawing: its subject size,
880 by 296. A loupe: nine rows, beside the memory it shows.
- **What it draws.** The rows as the working frame draws them, the marks
of the moment (current, struck, read, held, trail), the thread across the
gutter between source and disassembly, and an outline round each of the
working frame's windows: a 2-unit `dim` frame, 4 out. No link and no
projection: a step's ties are the working frame's.
- **What reads where.** In a 4K export the map filling the frame is 20
pixels to a row's text and reads; at 1440p 13 and reads on a monitor; at
1080p 10, a texture of shapes and inks in which the windows, the gold
rows and the vermilion of a write are what is seen. The caption carries
it there, and the map is never on screen for reading at 1080p: it is
for where, not for what.
**The minimap** is the map at a twentieth, 192 by 108, in the working
frame's corner: the caption band's right end, 1664 to 1856 across and 912
to 1020 down, under the clock's right end. The caption keeps its 1400 (it
ends at 1464); the clock's count moves left of the minimap, ranged right
at 1648.
| Part | Drawn |
| --- | --- |
| ground | the page, framed 1 in `rule` |
| panels | each map panel's outline, 1 in `rule`; a lens's drawing a `raised` block; a loupe a `lift` block |
| rows | each row of text a stroke 1 high, from where its text starts as long as it is (a twentieth of its characters' width), in its dominant ink at 45% toward the page: the file's shape, the stack's chains, a dump's bytes |
| windows | each working panel's window, 1 in primary, the panel in focus 2 |
| marks | the current row a gold stroke across its column, 2 high; a strike a vermilion block 3 by 3 at the row's start; a read a 3 by 3 frame in read's colour; held a vermilion pixel; the thread a gold stroke across the gutter |
A mark outside every window is on the minimap and nowhere else: when the
step strikes a word the stack's window does not show, its block on the
minimap strikes with it, and `flash`es (a ring 8 across drawing out to
14 and gone, 12 f) so the eye goes there once. That is how nothing is
hidden at the working frame's size: it is only small. The minimap is
secondary action: it never starts on a primary onset's frame, it fades
and never travels, except its windows, which glide with their scrolls.
### clock and caption
- **`clock`**: a 2-unit rule the width of the stage at y 900; gold, 4
high, along it as far as the recording has run; `moment 72 of 95` in
mono 20, faint, ranged right at 1648, left of the minimap. It says where the recording is, so
at a walk and a run it is still while a step plays: when the step's
mark has landed, the step's piece of gold fades in (12 f; 8 f at a run)
and the count changes as the fade starts. At a sprint the gold grows
with the recording, linearly, and is the one thing that says "fast".
- **`caption`**: one or two lines of at most 64 characters, Go 40 on 54,
ranged left on the margin; code in it is mono 35. Hex in it is unbroken
too. What a scene author checks, characters counted as shown:
| Rule | Number |
| --- | --- |
| on screen, from arrived to leaving | at least 1.5 s + 0.06 s a character (90 f + 3.6 f) |
| on screen | at most 12 s; a longer stretch wants a second caption or a shorter scene |
| before the first step it describes fires | 60 f after it has arrived; 120 f for a scene's first |
| a scene's first | arrives at 1.0 s; the first step fires by 4.0 s (5.0 s when the scene opens on the map and dives) |
| changes | only in a rest, never under a moving thing |
| longer than two lines | two captions, split at a phrase rest |
| the last | its reading time before the cut, and 2 s on the finished picture; the scene grows to fit |
- **`veil`**: the page at 50% over the panels a named beat does not
touch, and over what a pace cannot show ([`run`, `sprint`](#6-verbs));
at 65% under the camera. In over 18 f, out over 18 f.
- **`card`**: a title or the legend ([mock 6](mock/06-title-legend.png)).
The only frames with no context.
- **Camera rests**: x1 (the frame), x1.5 (1195 by 560: a column, or the
band), x2 (896 by 420: sixteen rows), x4 (448 by 210: one chain). It is
for reading, and always comes back.
## 6. Verbs
Frames at 60 a second. `s` is the frame a strike lands. Curves:
`standard` (0.3, 0, 0.2, 1) for things arriving; `glide` (0.45, 0, 0.55,
1) for things travelling and cooling. Charts: [`motion.md`](motion.md).
| Verb | On | Chart |
| --- | --- | --- |
| `fire` | the current plaque | 0 to 12: it pulses once. Nothing else moves |
| `arm` | a value about to be written | s-12 to s: the `armed` frame, in over 2 f; the old value still in it |
| `strike` | a value written | s to s+6 the fill comes in, linear; the new digits at s+3; s to s+12 its edges go out 3 units (4 in a lens's cell) and back, sine; solid until the advance |
| `cool` | a struck value | starts with the advance: 24 f, `glide`, the paper to nothing, and the turned corner of `held` fades in over its last 6 f, for three steps (then out over 36 f); the same in a lens's cell. The digits go to their ordinary face at its middle |
| `read` | a value read | in over 6 f; held to the advance; out over 18 f. No arm, no pulse |
| `extend` | a chain whose first hop was struck | each later hop is followed again, 4 f apart, fading in over 6 f |
| `link` | a `reg` just struck, and its target | s+6: the old pin fades (12 f) and the line draws from the register's row, head first, 24 f (36 f over 400 units), `standard`, the pin riding its head; the pin lands with the head and settles (12 f); held; at the advance the line draws back into the pin over 18 f. A target out of the window: the line ends in its stub, and the pin waits for the window |
| `project` | a run read or struck, and its part of the drawing | on the run's mark: the bracket on the row (6 f), the line draws from the bytes to the drawing (18 f; 30 f over 600 units; `standard`); only when it arrives does the part react (its own `read`, or `arm` and `strike`; a new call's node fades in, 6 f); out with the advance, 18 f |
| `travel` | a value, a card or a pin going from one place to another | `glide`. A value or card: 30 f to 200 units, 36 f to 400, 48 f beyond. A pin goes along its lane, 18 f after the strike that moved it: in a drawing 30 f to the next node or cell, 36 f to one farther; in the stack's lane 24 f to the next row and 2 f a further row, 36 f at most. A pin that comes fades in over 12 f rising 8 units; one that goes fades out over 12 f; a name joining or leaving a pin cross-fades over 12 f. On a `link` the pin rides the line's head instead. 8 f at a run; at a sprint only at a phrase's end |
| `open` | a loupe, from a pointer | the pointer's hop framed `read` (6 f); the stem draws from it to the loupe's place, head first, 18 f (30 f over 600 units), `standard`; the loupe rises with the stem's head: it fades in over 12 f from 8 units lower, its shadow growing from nothing to its offset (18 f, `standard`); the target's bright frame lands 6 f after. From a pointer inside a loupe the same, over it, and a third closes the first as it starts. In the slot of the level that read the pointer, or on a beat the caption names |
| `close` | a loupe | the deepest first: its stem draws back into its pointer (12 f) and the loupe sinks, fading out over 12 f as it falls 8 units and its shadow shrinks; with the advance of the step after the one it opened in, unless the narration holds it; 120 f at most without a change |
| `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 |
| `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 |
| `continue` | a stop far from the last: a breakpoint, not a step. Where the windows' new places are farther than their own heights (another function, another file), it is told on the map: `surface`, the jump there, `dive` | `fire` on the line it leaves from; then the levels as in a `cascade`, but CPU is a wave: every register that changed is struck 2 f after the one above it, in pwndbg's order, the fill in over 6 f, no arm and no pulse (a dozen pulses at once are a flash, and a dozen arms a crowd); memory: the stack's window scrolls or fades to its new place, and the [backtrace](#backtrace)'s frames leave, slide and arrive; the idea; hold 36 f after the last strike; `advance`, the source and disassembly fading through if far; rest. Its marks are only on what was on screen to change |
| `run` | steps that need not be read | 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; values change with an ember, never a solid; no ties but the thread. Registers, stack and disassembly are veiled from the first shortened step to the last; the source, the band and the clock are not. 24 steps at most. A run longer than a phrase may `surface` and play on the map |
| `sprint` | steps to be got through | 4 f a step. The drawing grows and the clock sweeps; the source and the band's view are veiled as well; the mark and the pins move only at a phrase's end. Each change of pace ramps at 0.6 of the step before. A sprint plays on the map: `surface` before it, `dive` after it, at the stop it reaches; the windows glide with the pc, the minimap's marks flash and fade |
| `establish` | a scene's opening | done by 54 f: the panels fade in, 18 f each, 6 f apart (registers, stack, source, disassembly, the band's view, the drawing's panel: 0 to 48); from 30 f the drawing's elements fade in rising 8 units, 12 f each, 2 f apart in address order and all begun by 42 f, each with its row's quiet bracket (an `echo`: no lines). The first caption arrives at 60 f |
| `scroll` | a `source`, `disasm` or `stack` window | whole rows, 24 f, `glide`, before the level it makes room for; marks ride with their rows; the window's outline on the minimap glides with it, the same 24 f. A column's `lead` and the line numbers are the rows' on screen: they change on the scroll's first frame, never before. A window going farther than its own height (ten lines, nine instructions, six slots) does not scroll, which would only blur: it fades out (12 f) and in at its new place (12 f), and what it brings comes in with no marks |
| `relayout` | a change of split | the drawing fades out (12 f); every panel moves to its new box, clipped to the box as it moves (48 f, `glide`); the drawing fades in at its new size (12 f). Nothing else moves under it |
| `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`. The panel's tag and whole rows in frame, the rows the visit's steps change in its middle third, never at its edge; a stack visited holds its window still. A visit never veils or clears a panel a drawn tie starts or ends in: it waits until the tie has drawn back, or frames both ends. 120 f at most without a change; back |
| `say` | the caption | out 12 f, gap 6 f, in 18 f; the numbers are under [caption](#clock-and-caption) |
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.
## Composition
**What may contain what.**
- 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.
- 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
states are `focus` and veiled.
- A tie sits over panels, in channels. It joins `place`s that blocks
publish (`reg`, `slot`, a word, a node, the line, the pc); it never
reads a panel's layout.
- A panel is `32 + 24 n` high. Panels do not overlap and are 12 apart.
**Adding a block.**
1. Name it: one word, a noun, not in the vocabulary.
2. Compose it from the layers above. If it needs a new atom, add the atom
first, on its own.
3. Give its states as `mark` states. A new state needs a new form, not a
new colour.
4. Publish its `place`s.
5. Give its motion in the verbs. A new verb only when no sequence of the
existing ones says it.
6. Draw it in the gallery in every state, at x1 and at 480 wide.
7. Add its row to the vocabulary and to the mocks table.
**Forbidden.**
- Information carried by hue alone. Every ink has a second sign (a name,
quotes, a position, a paper) except heap against data, which is
admitted above.
- A mark under coloured digits, except a strike for its 0.6 s and the
gold ember of a current row.
- A tie across text, or across another tie. More than three drawn ties.
- Two strikes landing in the same frame. Two writes of one step are 6 f
apart, in the order they happened.
- An effect before its cause: a drawing changing before its bytes, a
card lifting before its bytes are struck, a result stored before the
kernel returns it, a current mark moving before the hold.
- A mark wider than what changed: bytes struck that kept their value.
- A mark on what the viewer could not have seen change: a window that
faded to a new place, a panel that came in after its step.
- A text scrolled farther than its window's height: it fades through.
- A pin that jumps, two pins for one name, two names in one place.
- A space inside a number. A row that wraps. Rows that reorder.
- Anything hidden to make room: a row that cannot hold its chain ends in
`more`, a panel that cannot hold its rows ends in a count, a link whose
target is out of view ends in a stub and a count, a label cut short
ends in `…`.
- Mono under 20, sans under 18. Lines under 2 units. Dashes finer than 12
on 8 off.
- Alpha tints (but the veil), gradients, glow, grain, rounded panels.
- Solid vellum for anything but the kernel. Gold for anything but where
execution is.
## 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/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`).
```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
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
python3 -B gen.py # 1 to 8, then resvg the same way
```
| Mock | Is | Blocks it shows |
| --- | --- | --- |
| [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 |
| [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 |
| [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` |
| [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` |
| [8](mock/08-far-view.png) | first pass | `pages` |
Mocks 1 to 8 were drawn as whole frames before the context existed. Each
is now what its lens looks like under the camera; none shows its lens in
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).
- `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
stub off the window. A variable's pin.
- The stack's window held for a visit with `free` slots.
- `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
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).
- `pin` with a count; `rwx`.
- Every verb: the mocks are stills. `establish`, `link` and `project`
have no chart from a render yet.
**The data in 9 to 21** is the recordings': registers, chains, stack, the
instructions and their lines (12: `ztrace show` on
`anim/zig-out/recordings/steps.ztrace`, lines from its binary by
`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.
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
arguments on 12's spans and rows are the calls' own, from the tree.
**At 480 wide** no digit of the context reads. What is left: the layout,
the gold rows and the thread, the strike on `rdi` and its link into the
band, yellow and blue as texture, the caption whole. Through x264 at 720p
(CRF 28) mock 10's dump, its faint padding bytes, its dots and the chains
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).
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).
**What the recordings must hold for the map**, 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.
## 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.
| 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 |
Unchanged and already there: the 1920 stage and its splits, the palette
with the marks of the last round (`wash`, `struck` `b54f42`, the corner),
`metric.slot` with its offset and role, `metric.bytes`, `metric.pin`,
`metric.node`, `metric.calls` (full), `metric.tie` (54, 950, 962),
`stroke.tie`, `time.strike` (with `corner`), `time.link`, `time.project`,
`time.pin`, `time.continue_wave`, `time.relayout_fade`, `time.flight`,
`time.caption`, `caption_lead`, `time.run`, `sprint`, `ramp`, the
camera's scales.
## Building it
1. Atoms: `address` (unbroken, `lead`), `arrow`, `value`, `mark`, `pin`,
`bracket`. The gallery starts here.
2. `chain`, then `reg` and `slot`: the registers and the stack at rest.
3. `insn` with its columns and annotations; `line`; `thread`.
4. `bytes` and `hexdump`; `nodes` in the band; quiet brackets.
5. `strike`, `cool`, `read`, `extend` at density; the `cascade`.
6. `link` and `pin`; `project`; `echo`.
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.
Export:
```sh
canim --export - --size 3840x2160 --fps 60 --frames N |
ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - \
-c:v libx264 -crf 14 -preset slow -pix_fmt yuv420p \
-g 600 -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv out.mp4
```
1440p and 1080p are the master downscaled, never rendered at their own
size: `ffmpeg -i out.mp4 -vf scale=2560:1440:flags=lanczos …`. The map,
filling the frame, is drawn at half its units: 20 pixels a row's text in
the 4K master.
|