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
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
|
# 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 (those the scene moves
followed as far as they point, the rest with their values), the
instructions round the pc under 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.
9. **Down is deeper, and what acts together sits together.** The idea
over the source, a line over its instructions, a call over its callee,
the program over the kernel. Execution goes down and across; what it
means comes back up. A pointer and its target, a call and its callee, a
drawing and its bytes are neighbours
([direction and nearness](#direction-and-nearness)).
## Vocabulary
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` |
| | [`width`](#width) | an access's size in byte cells, where no register says it | 1, 2, 4, 8 cells; a count past 8 |
| 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop; opens a `loupe` |
| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`); `parts`: its eight bytes and the names its low ones go by |
| | [`slot`](#slot) | a word of the stack and its chain | pins; `free` |
| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside`, `waiting`, `pass`; the annotation `tied` (the default) or `whole` |
| | [`line`](#line) | a line of source | `current`, `trail`, `waiting`; wide numbers |
| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs (`size`, `protected` among them), marks per byte; wide address |
| | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` |
| | [`arc`](#arc) | a pointer to a row of the same panel, drawn | standing, `touched`; a stub |
| 3 panel | [`registers`](#registers) | all seventeen: a row each for those the scene moves, the rest three to a row | `quiet` |
| | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | what the state column has left: 12 to 20 slots |
| | [`backtrace`](#backtrace) | the call chain as rows, newest at the bottom | in the `none` split; the view of `calls`; a lens's drawing |
| | [`source`](#source) | a window on the file | 14 lines, 8 with a lens |
| | [`disasm`](#disasm) | the instructions round the pc, under the source | 17 or 11 rows; a [`descent`](#descent): a window a call deep, the kernel at the floor; a [`graph`](#graph): the function's blocks, as `rings` or in `layers` |
| | [`lens`](#lenses) | a drawing of some state over the program column, and over the state column the pane it is a view of; with no view, the drawing alone | `beside`, `subject`, `blocks` |
| | [`hexdump`](#hexdump) | memory, a `bytes` row a line | typed or by `fields`; `eight` (a stack frame, a word a row); `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) [`syscalls`](#syscalls) [`blocks`](#graph) `pages` | the drawings a lens can hold | `nodes` in two rows, a `bin` heading the second |
| 4 tie | [`thread`](#4-ties) | the current line is these instructions | standing |
| | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin`; a stub when that is out of view |
| | [`projection`](#4-ties) | these bytes are that part of the drawing | for a step |
| | [`echo`](#4-ties) | the same mark in two panels at once | for a step |
| | [`touch`](#4-ties) | this instruction reads or writes that word | for a walked step, while the row is current; `tied` only |
| | [`carry`](#4-ties) | this value went from that word to this register, or back | a scene's knob, off by default; for a walked step |
| | [`aim`](#4-ties) | this word holds the address of that instruction | the author's knob, off by default; for a step, or standing through a beat, or drawn on its beat and then standing |
| 5 frame | [`stage`](#5-the-frame) | the working frame: the band and the two columns | split `none`, `beside`, `subject`, `blocks` |
| | [`segments`](#segments) | the process's address space to scale, each end enlarged, its bands' addresses at their edges | treatments A (default), B, C; the ink's source: a band framed when a word is inked; a dump's place |
| | [`aligned`](#aligned) | the source and its instructions in one panel, each line level with its code | `interleaved`, `columns`; a split a scene chooses |
| | [`pair`](#pair) | two runs of one program against each other, a seam between them | `only here`, `differs`; each run's frame as bytes, an ASan run's shadow beside its rows |
| | [`map`](#the-map-and-the-minimap) | the working frame unfolded, every panel whole: 3840 by 2160 | the key |
| | [`minimap`](#the-map-and-the-minimap) | a pane's whole column of the map, small, in a strip at its right | its window, marks, `flash` |
| | [`clock`](#clock-and-caption) | where in the recording | its label: the chapter |
| | [`chapter`](#clock-and-caption) | a part of one scene with a title of its own, opening on the last picture of the part before | its title said at its seam; its name the clock's label |
| | [`column`](#column) | the second form a scene is composed in: the panes a beat is about in one column, its narration in the other | the `shelf` of folded panes; text on the right, or on the left while the program column is empty |
| | [`bubble`](#column) | a piece of narration placed in the frame, level with what it speaks of | `beside`, `below`, `above`, `on`; newest, older; its `stem` |
| | [`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` `touch` `carry` `aim` `travel` `follow` `advance`](#6-verbs) | what one block does | |
| | [`open` `close`](#6-verbs) | what a loupe does | |
| | [`descend` `cross` `ascend`](#6-verbs) | what a descent does: a call followed down, a system call, a return | |
| | [`regroup` `ink` `enlarge` `column` `frame up` `decode` `align` `unpack` `pack`](#6-verbs) | what building a view does (the introduction) | |
| | [`fold`](#6-verbs) | what the registers do: the quiet ones into their cells, three to a row (on a beat, or in a `dive`) | |
| | [`leave` `turn` `reach` `unfold`](#6-verbs) | what a graph does: a block left along an edge, a loop's turn round its ring, a block or an edge reached the first time, a fold opening | |
| | [`dive` `surface` `flash` `unroll` `roll`](#6-verbs) | between the map and the working frame; a pane and its whole column | |
| | [`cascade` `continue` `run` `sprint` `establish` `scroll` `relayout` `visit` `say` `title`](#6-verbs) | what a frame does; `title`, what a scene in chapters does at a seam | |
## 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 a column at a time, small, in a strip inside each pane of the
working frame as its [`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 |
| `size`, `protected`: malloc's words, read as below | primary: what is stored is not where it points | raised, one rect a field |
| `text`: a field read as text | a string's | raised, one rect a field |
| `loose`: a byte of no field: the allocator's between allocations, a struct's padding, what lies past the thing the dump is of | dim | none |
| `unread`: not observed at the stop shown | two 4-unit squares, faint | none |
`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).
### width
How many bytes a memory access touches, drawn as that many byte cells,
where nothing else in the instruction says it. It replaces the
disassembler's size words (`byte ptr`, `dword ptr`, `qword ptr`), which
are dropped from every operand ([`insn`](#insn)).
- **Form.** Cells 5 wide and 10 high, 7 apart, in `dim`, standing on the
baseline 3 after the operand's `]`; what follows the operand goes on 4
after the last cell: `[rbp - 0x60]▮▮▮▮, 0x10`. One cell for a byte, two
for a word, four, eight. Wider (`tbyte`, `xmmword` and up): eight cells
and the count in faint mono 20.
- **When.** Only where no register outside the brackets of the same
instruction has the access's size, and the mnemonic does not fix it:
`cmp [rip + 0x11018b]▮, 0` (an immediate), `mov [rbp - 0x60]▮▮▮▮,
0x10`, `movsxd r10, [rbp - 0x30]▮▮▮▮` (the register is 8, the read 4).
Not on `mov rdi, [rdi + 8]`, `mov [rbp - 0x38], eax`, `push`, `pop`, a
`call` or `jmp` through memory (always 8), `lea` and the padding `nop`s
(they touch nothing).
- **Why cells.** A numeral under mono 20 breaks the floor; a suffix on the
mnemonic (`movl`) is a second syntax. A byte is already a cell in every
dump, so four cells read as four bytes.
Mock 17.
## 2. Rows
Every row is 24 high and one line. None wraps; what does not fit is cut at
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.)
**`parts`**: a register's value as its eight bytes, and the names its low
bytes go by, for a beat that says so: code names a register by its parts
(`mov edi, 0x10` writes rdi's low four bytes, `xor eax, eax` rax's), and
the panel shows the whole register, so where the narration ties the two
the row opens in place ([mock 59](mock/59-regs-parts.png); the
introduction's II5). It is the regroup's idea read the other way: a word's
digits are its bytes, and the low ones are on the right.
| Row | Drawn |
| --- | --- |
| the register's | its name at 12; from 72 its eight bytes as a dump's (`byte`: two digits in 24, a pitch of 30, no gap), the high byte first as the number is read, so its low bytes are on the right; the zero bytes over its highest non-zero one at 45% toward the page (`pad`). Its chain is not drawn while it is open |
| a part's, one under it for each, widest first | a 2-unit bracket in `dim` under the bytes the part is, ranged right with the low end, its serifs 11 up toward them, 3 out from the first byte and the last; the part's name ranged right 10 before the bracket's left end, mono 20, `dim`: so each name stands where what it names begins. rax: `eax` 4, `ax` 2, `al` 1 (rbx, rcx, rdx likewise); rsi: `esi` `si` `sil`; rdi: `edi` `di` `dil`; rbp: `ebp` `bp` `bpl`; rsp: `esp` `sp` `spl`; r8 to r15: `r8d` `r8w` `r8b`. `ah` (the second byte of the first four) only when an instruction names it |
Marks: the part an instruction names is framed as read with its operand,
its own row and its bytes in the register's row together (an echo, 6 f); a
write strikes the bytes whose value changed and no other, as a dump's
(`09` to `10`: one byte), and the row's annotation with them. A write to a
4-byte part zeroes the four above it, which strike where they were not
zero. One register opens at a time, in a walked step or a rest, never at a
run; it opens and closes by [`unpack` and `pack`](#6-verbs). The rows
under it make room and close up again: the panel grows by three rows while
it is open (the state column under the registers must have them; in the
introduction it is empty then).
### 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 | hex, faint, ranged right in four characters, from the newest frame's base: the register its code addresses its words by (the call frame information's CFA register: rbp in a body that keeps a frame pointer, rsp at a function's entry, in its prologue before `mov rbp, rsp`, after its `pop rbp` or `leave`, and in a function that keeps none), so that `[rbp - 0x18]` and its word's `-18` are one number. The base's row is `+0`. Under [`whole`](#insn) pwndbg's: from rsp, `+18`, and `-8` above rsp. In the introduction, from 0x10 up with `0x` (`-8`, `+0x10`, `-0x18`), as the operands and the values are written: beside a symbol's decimal offset (`main+50`) a bare `-10` after `-8` reads as ten. Only there: the user chose to keep it an aid for newcomers, and every other scene keeps pwndbg's bare hex |
| 184 | address | stack ink, `lead`; then the chain, its first hop the word's content |
| 88 | shadow | in a run built with AddressSanitizer: the shadow byte that stands for this word's eight bytes, a `byte` cell in the pin lane's end, before the address it stands for (a fake frame's words have no offset from rsp, and no pins). `00`, addressable: faint, no paper. `f1` `f2` `f3`, the stack's left, middle and right redzones: bright on the `freed` hatch, the poison's sign. `01` to `07`, the first k bytes addressable: bright, the hatch over the other 8 − k eighths of its cell. The panel's tag gives where the shadow is, `shadow at addr >> 3 + 7fff8000` |
| 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), and which part of the word when it is narrower (`n, high half`, `f, low half`); at the process's start `argc`, `argv[0]`, `argv end`, `envp end`, `auxv` (dim). It is the name a `tied` annotation gives the word ([`insn`](#insn)) |
| 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. The introduction, which
leaves nothing to the eye, gives it the role `the way back` (its caption's
words; `return address` would cut the name beside 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: the window's
headroom, the words a pop or a return has just released, and every word over
rsp while the window is held still for the camera ([`visit`](#6-verbs)). Its
address at 60%, its word in faint, no chain, no role. A push fills it; rsp's
pin reaching it makes it the frame's.
### 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; `nop` and `endbr64` faint, with their operands: padding, which touches nothing |
| 264 | operands | as the disassembler writes them, whole, less the size words (`qword ptr `): a [`width`](#width) after the bracket where no register says the size. A jump's or call's target is an `address` in code ink; a PLT stub's, named by the stub: `401070 open@plt` |
| 564 | annotation | from 564 (540 in a pane with a [minimap](#the-map-and-the-minimap), whose strip takes 48 of the row), or a character after operands that run past it: what the instruction did, in the form the scene chose (below); a chain is cut at its far end by the chain's rule |
**Wide addresses.** An address of more than seven digits (a library's
twelve, `7ffff7d10fc5`) moves every column right of it by the extra, 12 a
digit: in libc the mnemonic is at 240, the annotation at 624. The width is
the window's own: in a [`descent`](#descent) the caller's window does not
move when libc's opens under it.
**Room.** The row holds 50 characters from 264, to 12 from the panel's
edge. Operands are never cut where the row has room, and never inside
`[]`: we do not hide what the instruction says. When the operands and the
whole annotation do not fit, in this order:
1. the annotation moves left to where it just fits, never left of 564 (540 beside a minimap);
2. the operands give way to the annotation: they end where it begins, in
a faint `…`. A cut that would fall inside `[]` falls before the `[`,
and the annotation's first hop is the address the brackets named.
| 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 |
| `waiting` | a call whose callee's window is open under it, in a descent: the plaque's place ringed (a 2-unit primary frame 24 by 24, a primary head in it), as a waiting call node is; no wash. Its annotation is the call in C's form: `open("note", O_RDONLY)` |
| `pass` | a stub's jump, gone through on the way down: a trail bar; the call lane runs on from it |
**The annotation's form** is a scene's knob, `annotation`, with two values. A scene that says nothing gets
`tied`; one asks for the other with `annotation = .whole`, for the scene or from a beat on.
- **`tied`** (the default). Every fact is printed once, in the pane that holds it, and the row names it there.
A word of memory the instruction reads or writes is named, not spelled out: the annotation is the word's
name and the value that moved, one hop, and the word's own row holds its address and the rest of its chain.
The name is the word's role in the stack ([`slot`](#slot): a local `next`, `n` for the high half it lives
in, `saved rbp`, `argv[0]`) or a global's symbol (`head`), bold, in the ink of the region it lives in, as a
variable's [`pin`](#pin) is; the grammar is the chain's, the name standing where the address would:
`next → 405010`, `prev ◂ 0`, `saved rbp → 7fffffffed00`. A register the instruction sets is the small `reg`
cut after its first value, `rax 405010`: the chain is the registers pane's, where it is struck in the same
frame. With `tied` the stack counts its offsets from the frame's base, so the operand's displacement and
the word's offset are one number (`[rbp - 0x18]`, `-18`), and a walked step draws its
[`touch`](#4-ties) from the row to the word. The row is half as long (`next → 405010` for
`7fffffffecc8 → 405010 ◂ 7`), and the value it wrote is never the part cut off: beside a minimap the whole
chain of a stack store is cut to `7fffffffecc8 → …` (mock 44).
- **`whole`**: the annotation as pwndbg prints it, a chain from the address the instruction computes
(`7fffffffecc8 → 405010 ◂ 7`), and the stack's offsets from rsp. For a scene whose story is the address
itself (where a store lands in the ASan pair, a heap scene reading the allocator's words, the introduction
before the stack has a pane), and for a frame with no stack pane at all.
Under `tied`, where the word has no name or no pane holds it, the row falls back, that row alone:
| The word | Its annotation under `tied` |
| --- | --- |
| a slot in the stack's window, with a role | its name and the value: `next → 405010` |
| a slot in the window with no role (a spill, a temporary, the canary's copy) | its address and the value, one hop: `7fffffffecd0 ◂ 1`; the slot's offset says where it is |
| a slot outside the window | the window scrolls to it first, in memory's slot of the step before the row fires ([`scroll`](#6-verbs)), so it is never outside when it is touched; where the window cannot go (held still for a camera [`visit`](#6-verbs), another thread's stack) the whole chain, its name in place of the address |
| a word a dump or a loupe on screen shows (the band's view, a loupe) | its address and the value, one hop: `405038 → 405010`; the run's mark is the [`echo`](#4-ties); no touch, the view being far |
| a word no pane shows (a global, the heap with no view) | the whole chain, as `whole` draws it, its name in place of the address where it has one: `head → 405050 ◂ 9` |
**The operand** is the encoding and stays as the disassembler writes it, less its size word: `[rbp - 0x18]`,
primary. The name is the annotation's and is never written into the brackets: IDA's `[rbp+next]` (way C of
[mock 48](mock/48-tied-ways.png)) reads well but hides the displacement the stack's offset column matches, and
asks the viewer to know that `next` is −0x18.
**What stays in the row** under either form, because no pane holds it: a compare's two values and the flags
it leaves; a conditional's `taken` and the flags it reads; a call's arguments, its result, and the call in
C's form; `lea`'s sum; an indirect target and the slot it was read through; a `rep`'s count; a system call's
name, number and arguments; a return's destination.
**The annotation**, by what the instruction does:
| It | Annotation |
| --- | --- |
| reads memory | `tied`: the word's name and the value read, `prev → 405050`; `whole`: a chain from the address it computes, `28b41098 → 28b41070 ◂ 9`. Before the step, where it will look; in the step the name (the chain's first hop) is `read`, an [`echo`](#4-ties) of the word's own frame. The value is read at the access's width: a 4-byte load of `n` is `n ◂ 15` (`7fffffffecc4 ◂ 15`), not the word round it |
| writes memory | the same; the value is `struck`, in the frame the word is |
| only sets a register | a small `reg`: `rax 28b41090` (`tied`), `rax 28b41090 ◂ 4` (`whole`) |
| moves rsp or rbp | the move in its own terms, first: the amount, `rsp -8`, `rsp -0x18 3 words`, `rsp +0x18`, `rbp = rsp`; then the word it writes or reads, by its role (the value is the pushed or popped register's, in the registers): `push rbp` is `rsp -8 · saved rbp`, `pop rbp` `rsp +8 · saved rbp`, `leave` `rsp +0x20 · saved rbp`, a `call` `reverse() · rsp -8`, a `ret` `→ 401272 main+50 · rsp +8`. The amount is struck with rsp's strike (an echo); the stack's answer is the [stack's own instructions](motion.md#the-stacks-own-instructions) |
| computes the address of a named word (`lea rsi, [rbp - 0x30]`) | `= &buf`, the name in its ink; the register's pin lands on the word's row (a [`link`](#4-ties) to a slot) |
| compares or tests | the two values it compares, ` : ` between, faint: `3 : -4096`; then the flags it leaves, those the conditional after it reads (CF ZF SF OF when none follows): set on a chip as rip's are, clear in dim lower case: `3 : -4096 CF zf` |
| jumps on a condition | `taken` in primary, or `not taken` in dim, then `· reads` and the flags it reads, as the compare drew them; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37`. While it is current, the chips on the row that set them are framed as read with it (an `echo`), and rip's |
| computes an address (`lea`) | `=` and what it made: an address and its chain (`= 402004 "note"`), or a number. With room, the sum first, each register's value in its ink: `rbp 7fffffffed00 - 0x30 = 7fffffffecd0` |
| calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there. Through a PLT stub: the function the stub reaches, `open` (or `the resolver` while its GOT slot is still lazy). A direct call whose operand already names its callee (`4011a0 reverse`) says the call in C's form instead, `reverse()`, `push(9)`. Once it has run: the call in C's form and its result, `open("note", O_RDONLY) = 3`. The word it pushes is the stack's: the call's [`touch`](#4-ties) goes to it |
| calls or jumps through memory or a register | where it goes: `→ 7ffff7d10ec0 open`; then, faint, where that was read: `· read from open@got, 403fd8`. Out of room, the slot goes first, then the target's digits; its name stays: `→ __pwrite64` |
| reads a place the C library's layout names | the name, then the value: `fs:[0x28]` is `the stack's canary 191a6a1f012bed00` |
| repeats (`rep stosq`, `rep movsb`) | the count and the step: `rcx 12 · 8 bytes each`, the destination's chain after. Stepped by instruction a `rep` stays current while rcx counts down, an iteration a step |
| returns | `→ 10018b0 main+80`: the value of the word it reads, which is framed `read` on the stack with its touch |
| makes a system call | its name and number, `openat nr 257`; its arguments hang under it by name, as a call's; in a [`descent`](#descent) the kernel's window opens under its window |
Mocks 9 to 11 show the read, the register-setter, the taken jump and
`outside`; 12 a call with its argument, a write, and operands longer
than 24 characters with the annotation moved right of them; 14 an
indirect call by name; 16 a call through the PLT, `waiting`, `pass`, a
system call; 17 a compare and the conditionals reading it, a `lea`, a
named place; 44 and 45 a store and a load under `whole` and `tied`; 46 a
call's push and 47 a prologue under `tied`; 48 three ways of tying the row
to its word. A `rep`, and the flags' echo, are not drawn.
### line
The number ranged right in three characters, faint; the text from 64, in
the four code inks; 67 characters, then a faint `…`. `current`: gold
plaque on the number, the wash across. `trail`: the bar, for the last three
other lines run. `waiting`: the pc is in code with no source (libc, a PLT
stub, the vDSO) under this line's call: the number ringed, a 2-unit
primary frame where the plaque would be, no wash; the source's tag says
where the pc is (`main waits at line 6 · the pc is in libc's open`), and
the thread waits with it (primary, 2 units).
**Wide numbers.** The number column is as wide as the program's largest
line number, three characters at least: sqlite3.c's 262 899 lines take
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, but no space before a pointer's arrow, which has its own room as in a chain (`9 → 407030`): 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.
**Malloc's words**, for a scene about the allocator (elsewhere the size
word is the faint note above):
- `size`: a chunk's size word. The reading is the size, the three low
bits cleared, in hex as malloc's sizes are read (`0x20`), then the bits
as rip's flags are drawn, `A M P` (not the main arena, mmapped, the
chunk before in use): set on a chip, clear in dim lower case:
`0x20 a m P`. A bit that changes is struck and held on its chip.
- `protected`: a pointer glibc stores safe-linked, the pointer xor its own
address shifted right by 12. The bytes are what is stored, in primary
(`55 54 40`); the reading is what they protect, `→ 405050`, or `NULL`,
then the mask, faint: `→ 405050 ^ 405`. Its [`arc`](#arc) goes to the
pointer it protects. A NULL so stored is not zero (`05 04`, 405), which
the reading says.
- A field may carry a note from the scene, Go 18 faint, after its reading
or as its reading: `key`, `slots left · 1 in the bin`, `the old link`.
The reading replaces a hexdump's text column: where bytes are text the
reading is the text, in quotes; where they are a pointer it is the address,
so a little-endian pointer is read without leaving the dump. It is a list,
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 panel's 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. Reads the moment's
registers and mappings.
**`quiet`.** A register no step of the scene changes is folded: the
scene's own registers (those it writes, by the recording over the scene's
moments) keep their rows and their whole chains, with rsp, rbp and rip
always among them; the quiet ones follow, three to a row on a pitch of
285, under a 2-unit `rule` across, in pwndbg's order, and rip is the last
row, as ever. A quiet cell: the name in faint at 12, the value from 60 in
its ink, and a pointer's chain cut at once to `more` (`r12 7fffffffee38 →
…`): its hops are on the map, whole. A quiet register a step reads is
framed as read in its cell; one a step writes was never quiet (a scene
with a `continue` changes them all, and folds none). The set is the
scene's, chosen once: no row comes or goes while it plays. A scene that
builds the panel shows every register a row first and folds the quiet
ones on a beat of its own ([`fold`](#6-verbs)), after which the set holds:
the introduction builds it so in its chapter II, and its four chapters
share one set (rax rcx rsi rdi, rbp rsp, which II's call and continue
change; ten folded into four rows; 11 rows), as its clock is one.
The panel is as tall as its rows: sort moves eight (rax rcx rdx rsi rdi,
and rsp rbp rip) and folds nine into three rows, 11 rows, 296 high; the
list's `reverse` moves six and folds eleven into four, 10 rows; sqlite's
continues fold none, 17 rows, 440. Every row the panel folds is a slot
the stack gains.
### stack
`slot`s from rsp, low addresses on top (where it first stands beside a
drawing with high addresses on top, as the introduction's address space,
the scene says so: "lower addresses are drawn higher: down a word is up a
row"): as many as the state column has
under the registers ([the frame](#5-the-frame): twelve as the subject
beside eleven rows of registers, fourteen beside a lens, fifteen with
none, twenty with the `blocks` lens). `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)`, and over rsp its **headroom**, two words drawn
`free`: the room a push, a call or a `sub rsp` will take, there before they
take it. In a leaf whose locals lie under rsp (the red zone, at -O0 without a
`sub rsp`) the window starts at the lowest of them instead, rsp's pin on a row
inside it, since those words are the frame's and its instructions touch them.
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 the
headroom's 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
half (the fourth to ninth of twelve), and stays there until a step
touches a slot outside it.
- **When rsp or rbp moves, the rows hold and the pin travels** ([`travel`](#6-verbs)):
the move of a stack pointer is the event of its step, and is seen as a
move. rsp's pin climbs (a push, a call, a `sub rsp`) or falls (a pop, a
`ret`, an `add rsp`, a `leave`) row by row along the pin lane, the amount
on it as it goes (`rsp -18`, in write's vermilion); each row it reaches
is gained (it brightens from `free` to the frame's, and its role arrives)
or released (it goes quiet, `free`); a 3-unit vermilion bracket in the
outer arc lane spans the rows it crossed; the newest frame's span
stretches or shrinks with it; its register is struck as it lands. rbp's
pin flies the same way to where rsp is (`mov rbp, rsp`), the two meeting
on one row in pwndbg's order; rsp's to rbp's (`leave`).
- **Then the window follows** ([`follow`](#6-verbs)), never with the travel:
once the pin has landed, if fewer than two free words stand over rsp, or
the newest frame's return address has gone under the window's foot, the
rows glide by whole slots to give the headroom back (the pin riding its
row). Where the climb is longer than the room over the pin, the pin
travels to the top of the window and the rows slide under it for the rest,
one move on one curve. Where it is longer than the window (a `sub rsp` of
a page, an `alloca`), the pane [`unroll`s](#6-verbs) to its column and the
pin travels along it at the column's scale, the region gained marked on
it, and the pane rolls back in at the new place.
- 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. A scene may hold it the same way
while a frame is made: the introduction's chapter III holds it from its
first picture with four `free` words over rsp, enough for `push rbp` and
`sub rsp, 0x18`, so that only pins move and no row.
Tag: `twelve words`, or the range when scrolled (`rsp+20 to rsp+78`); what
the offsets count from, `· offsets from rbp` (`tied`: the frame's base, which
changes with the frame, a crossfade of 12 f) or `· offsets from rsp`; and
`· the frames they belong to`.
### backtrace
`call` rows, the oldest on top and the newest at the bottom: a call adds
a row under the others and a return takes it away, as the calls tree
grows down beside it. `#n` keeps gdb's numbering, `#0` the newest, gold.
A panel of its own in the `none` split, four
and then a count, under the stack; the view panel of a [`calls`](#calls)
lens, seven; the drawing of a [`backtrace` lens](#lenses), eleven as
subject and five beside, its `#0` just over the source line it is at; in
the other splits the stack's spans carry it.
More frames than rows: the oldest go from the top, and the tag's note
counts them, `newest at the bottom · 2 more above`. On the map it is whole.
On a stop far from the last (a [`continue`](#6-verbs)) the chain changes
as rows making room: the frames that end fade out (12 f); the frames both
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 with a lens up, of any
kind (the loop in hand: the scenes' functions are eight to ten lines, and
the minimap has the rest). 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
Under the source, in every split: a line over its instructions, the
thread between them in the margin. Seventeen `insn`s in address order:
the pc's, eight above, eight below (`none`, `beside`); eleven (five, the
pc, five) as the subject and with the `blocks` lens.
- 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.
- Where the recording has the function's blocks, each block's first row
is under a 2-unit `rule` across, and its visits are ranged right in
that row's annotation room (`×11`, faint) when it is free: the
[graph](#graph)'s pill in its digits.
On the map the column is 69 rows: the function whole when it fits, with
its neighbours round it.
A call the narration does not follow moves the window to the callee, as
above: the stack's spans and the backtrace carry the depth. A call it
follows opens a descent.
### descent
The disassembly a level up: a call followed down. The panel becomes a
stack of windows, one a call deep, the caller's on top and each callee's
under the row that called it, and under the deepest, while a system call
is made, the kernel. Down is deeper, and the way back up is drawn.
| Part | Drawn |
| --- | --- |
| a caller's window | its call row, `waiting`, one row after it (the row it will return to) and at least one before: three rows. The rows the deepest window does not use go to the nearest caller, above its call row; it never keeps more than the one row after the call, so the callee's head sits directly under its return row. Where the caller's function starts first, the rest go to the deepest window, its neighbours `outside` |
| a head | a row: a 2-unit rule across, the callee's name at 40 (Go Medium 18, primary), what it is ranged right (Go 18, faint): `libc.so.6 · no source`, `the PLT · its jmp reads open@got, 403fd8`, `vdso · the kernel's code, run here` |
| the call lane | 2 units, primary, from the waiting ring at x 14 straight down to the head, turning in to a head 7 by 8 before the name. It is part of the panel, as the jump lane is, and not a tie of the budget |
| a stub | its rows whole (a PLT entry is three); once its `jmp` has gone on, its window keeps that row, `pass`, and the lane runs on from it to the next head |
| the deepest window | as long as it needs: a stub whole, else the rows round the pc as the panel's; four of its rows under a `syscall` hold the call's arguments |
| the kernel | the floor: solid vellum, its head `the kernel` and the call (`openat, system call 257`); the call in C's form; `returns` and the value (struck as it lands), with what the crossing clobbered (`rcx, r11`). The crossing lane: 3 units, vellum, from the `syscall` row's plaque down to the vellum, its head in ink on it |
| the panel's tag | the deepest function and its module: `open · libc.so.6` |
In seventeen rows, the call to `open` at its `syscall`: main's three, the
stub's head and its `pass` row, the wrapper's head and eight rows, the
kernel's head and two rows ([mock 16](mock/16-descent.png)).
- **Depth.** Three windows of code at most, and the kernel. A longer chain
keeps the first and the last two; the ones between are one row, `more`'s
arrow and `2 calls: fib fib`. The stack's spans and the backtrace hold
the whole chain.
- **The source** stays on the deepest frame that has source, its line
`waiting`, while the pc is in code without it. Into a function of the
program's own the source follows the pc as it always does; the call's
line is in its waiting row's annotation.
- **Any call.** The program's own function: its window, its lines.
libc's: no source, its symbol and module. A PLT stub: its three rows,
the GOT slot named in its head; under lazy binding its `jmp` goes back
into the PLT and to the loader's resolver, which is one row of `more`
(`→ … _dl_runtime_resolve, 412 instructions`), and the GOT slot it
writes is struck in memory, where the data is. The vDSO: its window, no
kernel under it (the point of it); what it reads is the `[vvar]` page.
- **Up.** A `ret` closes the windows under its caller's, bottom first;
the caller's window grows back to the panel and its call row is `ran`,
its annotation the call and its result. A stub jumped through closes
with the function it jumped to: the return goes straight to the caller.
- **On the map** the column is the descent whole: each window its
function, whole where it fits, the kernel's under the last.
Its motion is [`descend`, `cross`, `ascend`](#6-verbs).
### graph
The disassembly's other form: a function as a graph of its basic blocks,
with what the run has done on it **by the moment shown, and nothing
after** (see Forbidden). It is the `blocks` lens's drawing, and on the
map that drawing at the same size. Two forms; a scene names the one it
wants:
- **`rings`**, the first: each loop a ring its blocks sit on, the mark
going round it the picture of iteration. For a function about loops.
- **`layers`**, the second: the blocks in layers, the path read down, a
fork two columns. For a function that is a tree of branches; with no
loop, `rings` draws exactly this.
A block in either is a **pill**, 24 high, its ends half circles, upright
(never turned to follow a ring): its offset from the function's start at
12 (`+2f`), the functions it calls after it, faint (`+5f swap`: a call is
not an edge; two named, then `…`), and its visits so far ranged right 12
from its end (`×11`, `dim`). As long as its words, 116 for `+2f ×11`.
| State | Drawn |
| --- | --- |
| not reached yet | on the page, a 2-unit `rule` frame, its offset faint, no count. What the code is (where the block is, its edges) is known from the start; what the run will do is not |
| reached | on `raised`, its offset primary, its visits |
| the pc's | framed gold, 3 |
| a fold | blocks not reached yet folded into one (below): dashed 12 on 8, `+5b … · 7` (its first block's offset, how many) |
| Edge | Drawn |
| --- | --- |
| not taken yet | `rule`, 2 |
| taken | `dim`, 2 |
| the last three taken | the trail's golds, the newest 3 units |
| its head | 8 by 8, on the target's frame, on the edge's last tangent |
Taken and not taken are told by ink and by form together: a taken edge
ends in its count's block being lit, and the jump's row in the
disassembly under the source says `taken` or `not taken` in words. No
dash means "never": that would need the rest of the run.
**`rings`.**
| Part | Drawn |
| --- | --- |
| a ring | a circle in the edges' ink, its blocks on it at their centres, clockwise in the order they run from the header, which is at the ring's left (9 o'clock), where the way in arrives from the left. Radius as its pills need, 12 between any two: sort's outer loop 140, its inner 84 |
| an edge to the next block on the ring | the arc between them, cut where each pill's frame is, its head on the arc's tangent |
| the back edge | the arc from the latch to the header, round the ring's foot and up its left: the loop closing |
| an edge inside a loop that passes blocks of it | a fork that rejoins: an arc 30 inside the ring from the one to the other (sort's `j > 0` failing, past `+2f`) |
| a nested loop | its ring outside its parent's, touching it at its header, which is the parent's block at 3 o'clock: the inner header at its own ring's 9 o'clock, so both rings run the same way |
| a loop's way out | along the ring's tangent at the block it leaves from, out of the pill's foot (30 in from the end farther from the ring), straight, then quarter circles of 16 to its target: from a header at 9 o'clock straight down outside the ring; from a block at 3 o'clock down the tangent, under the ring's foot, into its target's end. Never a chord across a ring |
| outside every loop | the blocks lie as `layers` lays them, a ring standing in its layer as one block: the entry to the left of the header, the blocks after the loop under it |
| the turns | at the ring's centre, 30 under it (clear of the line its 9 and 3 o'clock pills lie on): the number in mono 20 and `turns` in Go 18 dim, `5 turns`; nothing before the first |
Sort, clang -O0, at the 11th compare: two rings (the outer loop `+12 +1e
[+24] +5d +97 +99`, the inner `+24 +2f +56 +5f`), `+0` coming in
from the left, `+a7` under the outer header; 732 by 286, in a pane of 880
by 344 ([mock 43](mock/43-graph-forms.png), 25).
**`layers`.** Layers by the longest path from the entry, every back edge
found by a walk from it in address order (both from the code); a block
under its fall-through predecessor, a taken target to its right; edges
out of the foot by the side their target lies on, along the gap, into
the target's top; a back edge up its lane on the left; one that would
cross a block in the channel on the right; every corner a quarter circle
of 12. Layers 12 apart, lanes 10, columns 300. It grows down: past its
pane it pans by `scroll`'s rules, the pc's pill in its middle third.
**Nothing from after the moment.** The layout is the code's, made once
for the scene (where every block is, what a loop is), and never from the
run: no block placed by how often it will be reached, no fold of what the
whole recording never reaches, no edge drawn as never taken. What changes
is what the run has done: a block is quiet until the run first enters it,
an edge until the run first takes it, and that first time has a verb,
[`reach`](#6-verbs): the edge draws in gold under the mark, and the pill
fills to `raised` as the mark lands, its offset brightening and `×1`
fading in.
**Too big for its pane.** A function whose pills do not fit folds the
blocks the run has not reached yet: the code beyond each way the run has
not taken, as far as it leads, cut so that no fold leads back into
another, one dashed pill in the place of its first block (libc's `open`
at its `syscall`: `+5b … · 7`, the cancellable call's blocks, and `+be …
· 8`, the way back from the kernel). The layout keeps a fold's room as one
pill; when the run reaches a block in it, it opens
([`unfold`](#6-verbs)): the pills beyond it make room along the layout's
own direction (round the ring, or down the layers), never across it, the
fold's blocks fade in quiet in their places, and the reached one fills. A
fold only opens, never closes again in a scene, so the picture grows the
way the run does and nothing a viewer has learnt moves away. Then, if it
still does not fit, the pane pans.
**What the recording knows.** By instruction, every jump and return
carries the edge it took, so the path, the counts and the trail are exact.
By line or by breakpoint only the blocks the stops are in are known: their
visits are counted, the edges are drawn by kind in `rule` with no counts,
and there is no trail. A function past 2 048 instructions (`sqlite3VdbeExec`,
2 510 blocks) is folded from the start to its reached blocks and the folds
between them. Code with no bounds (start-up, JIT code) has no graph and
stays linear.
**What a static graph cannot show**, and this one does: how often each
block was entered and each branch went each way so far, the path the run
took (the trail), the block the pc is in, and the blocks and edges the
run has not reached yet, quiet until it does.
**Where it lives.**
- **The `blocks` lens**, for a scene about control flow: the drawing over
the program column, 880 by 344, and no view: the pc's block's rows are
the disassembly under the source (eleven rows), each block's first row
under a 2-unit `rule` with its visits so far, the thread from the
source's line to its run. The pill and its rows are tied by the pc's
gold and by the count's digits. No row is drawn twice.
- **The map** draws the drawing as it draws any lens's, at its size in the
frame, over the source; the disassembly column stays the linear 69 rows,
each block's first row ruled with its visits ([mock 22](mock/22-graph-sort.png)).
A sprint on the map reads as the gold going round the rings and down
the linear column together. A descent on the map draws the callee's
drawing under its caller's.
- **The disassembly's minimap** is the linear column, each block's first
row ticked at its left (2, `rule`), the pc's row gold.
The comparison the forms were chosen from, the `track` (a line of
blocks, loops as arches over it) among them: [mock 43](mock/43-graph-forms.png)
shows the two kept. The track is withdrawn: a ring says a loop and a
layer a branch, while a line of blocks said neither, and its arches were
rings flattened to fit a band that the frame no longer asks for. Its
motion is [`leave`, `turn`, `reach`, `unfold`](#6-verbs). Mocks 22, 24,
25, 43.
### 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)). A lens with
no view of its own (`blocks`, whose rows are the disassembly under the
source) is its drawing alone over the program column, 880 by 344, and the
state column is the registers' and the stack's from the top. On the map
the drawing keeps its size in the frame 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 |
| `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 calls so far, as strace writes them, oldest on top; the kernel's own side is the [`descent`](#descent)'s floor | a `hexdump` of the buffer the call is given or fills; the `registers` that carried it, by `echo` | 14; 16; 3 at camera scale |
| `blocks` | the function's [graph](#graph): `rings` (each loop a ring its blocks sit on) or `layers` (a tree of branches), every count the run's so far | none: its rows are the disassembly under the source, eleven | 25; 43; 22 on the map; 24 |
| `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.
There is no heap lens. libc's heap is a scene drawn with these blocks:
`nodes` in two rows (the program's list over malloc's free list), its view
the chunks by `fields` (`size`, `protected`), the free list as `arc`s, a
`loupe` on the tcache ([the heap scene](motion.md#a-scene-libcs-heap-from-the-inside),
mock 18).
A scene may change its lens where it stands: the drawing fades out (12
f), then the next fades in (12 f) and its elements come in as at
`establish`; a view the two share stays. The split does not move, so this
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`); or,
with no view, 856 by 296 (the `blocks` split's 344).
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. A lens whose elements
are rows the context already shows (the `blocks` lens's are the
disassembly's) has no view and draws no row twice.
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.
**Two rows**, for chunks that change hands (the heap scene): the
program's list on top, from its variable's pin, and under it the
allocator's free list, both in list order, 110 apart. A node goes from
one row to the other when it is freed or taken back (`travel`, 36 f). The
boxes are 136 wide, so a stale word can be read in the value's half.
- A node the allocator holds is drawn `freed`: its outline dashed 12 on
8, its first word's half the well and the link's square (glibc's tcache
keeps the link where the value was), the second half hatched with `key`
in faint. The arrow is the link as it protects, not as stored.
- **`bin`**, the second row's head: a raised box 160 by 44 at the row's
left, the bin's name in mono 20 (`tcache 0x20`), how many chunks it
holds on its shoulder as a call's result is (a square of 30, mono 25),
an arrow from its right edge to the first chunk. Before the bin exists,
the box dashed and faint (`dummy tcache`). The count is what the bin
holds, worked out from what glibc stores (2.44 stores the slots left,
16 less it; the loupe on the tcache shows both).
### hexdump
`bytes` rows, sixteen a row, a window of the region kept round the rows
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`, malloc's
`size` or `protected` ([`bytes`](#bytes)), or `bytes`,
left to the eye: on raised paper with no reading. A byte of no field is
`loose`. A field is a run, cut where a row ends. This is how a real
program's memory is drawn when the debug info does not type it, or the
meaning is the file's and not the C's (an SQLite page).
**`eight`: a stack frame as bytes.** Where what a step does to the stack
is a byte at a time (a loop storing into a buffer, a `strcpy`, an
overflow), the words of the [`stack`](#stack) panel hide it: a word going
`41`, `4141`, `414141` says neither that a letter was written nor where
one field ends and the next begins. The frame is then a hexdump by
`fields`, eight bytes a row, so that a row is one word of the stack:
| x | Column | |
| --- | --- | --- |
| 12 | pins | rsp's and rbp's `row` pins on their rows, as the stack's |
| 62 | shadow | in a run built with ASan, the row's shadow byte, as on a [`slot`](#slot) |
| 118 | address | in its region's ink, `lead`. No offset from rsp: the reading needs the room, and the pins say where rsp is |
| 274 | eight `byte`s | on a pitch of 30, each field's on its paper (`raised`), what no field covers `loose`. A field's run never crosses a row, so a boundary between fields is a row's edge or a gap in the paper |
| 522 | reading | the field's name in Go 18 `dim` (`buf[0..7]`, `i`, `saved rbp`, `return`), then what its type makes of its bytes: a buffer's text in quotes in a string's ink, a count in decimal, a pointer as `points` and its address and name. A pointer that is no longer an address reads as the number it is, `0x4141414141414141`, with no arrow and no name. A string too long for the row is cut at the frame's span with a faint `…` |
| 866 | span | the frame's [`call`](#call) span, as the stack's, its name on a row whose reading is short |
The fields are the frame's own, from the debug info and the call frame
information: its locals, the saved registers, the return address; in an
ASan run's fake frame its header (`magic`, `descr`, `pc`, `real stack`),
the buffer and the redzones. **A byte stored past the field the store
aimed at keeps that field's ink**: the letters a loop writes into `buf`
are in a string's ink in `buf`, and stay in it when they land in the
saved rbp and the return address, whose readings say what the CPU will
make of them (`→ 7fffffffed41`, then `→ 401141 fill+1`, then `0x41414141`).
So each turn is one more byte and one more letter, and the moment the
letters cross from one field into the next is a row's edge being crossed.
The store's byte is struck as in `bytes` (one byte, never the word).
It is the stack panel's other form, a scene's choice: the default
everywhere is the words with their chains; `eight` where the narration is
about bytes. A pair puts it in each column (mocks 26 to 28 and 38).
**`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, the last leaf's centre at 880 − 69 so its badge stays 12 inside the rule (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 program's conversation with the kernel. The drawing is the calls so
far as strace writes them, a row each, oldest on top and the newest at
the bottom: the name in bold, the arguments by name with their values
(`fd 3 "t.db"`, `buf 538b28`) where the recording has them, ` = ` and
the result, the newest's with the turned corner. Its view is a
[`hexdump`](#hexdump) by `fields` of the buffer, `given`, and it changes
with the crossing, never in one frame: the last call's bytes go (12 f)
and this one's come (12 f) while its arguments are framed (a path or a
buffer handed in is there whole; one the kernel fills is dots until its
bytes strike, 144 to 176); they leave when the log takes the call's row. The band is not
the kernel and is not on vellum: the kernel is under the program, the
floor of a [`descent`](#descent), where the call is made. A crossing
stepped over (a line that calls libc's wrapper, not followed down) opens
the same window under the call row: the wrapper is not shown, and the
kernel is still under the program.
A **crossing** is a step that makes one system call; its timetable is
[`cross`](#6-verbs) and [motion.md's](motion.md#a-system-call). What it may claim:
- A register is framed as carrying an argument only while it holds that
argument at the stop shown. Stopped in the caller of libc's wrapper,
`pwrite64`'s buffer and count are in rsi and rdx, but its descriptor is
not yet in rdi nor its offset in r10: those two are not framed, though
the kernel's window names them. Followed down to the `syscall` row,
all of them are.
- Nothing on the kernel's side changes before the crossing lane reaches
it. `returns` takes the value before the answer leaves, rax is struck
as it lands, and everything else the step changed (the registers the
call clobbered, pins, links, a result stored in memory) waits for rax.
The log's row comes in with `returns`.
- A step that makes several calls (a continue through a library) is not
a crossing: the log takes them, oldest first, 2 f apart, each fading
in; no lane, no kernel window, 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, at any moment of the step; where the first place
would, it moves down past them, then to the other side; it stays inside
the stage. **One hung from the band's view** (a row of the drawing's
bytes) never lies over the registers, which every step changes: it lies
over the stack, its tag's top on the stack's first row (in `subject` 568
to 720, over the first six of the stack's twelve), its left edge on the state column's, its
stem down the gutter's right lane (x 962) from the foot of its row to the
tag. Where the step changes a word of the stack under it, it does not open
in that step. On the map it is
a panel of its own beside the memory it shows (the map has room), and on
the working frame it has no minimap of its own: the pane it lies over keeps
its strip, covered where the loupe covers it.
**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. Every tie is a **relation**, and the relations
are one data problem, solved the same way for every kind: per frame, tables
of places and of values; the kinds as one table of properties; relations as
joins between them; and a resolver that is a pipeline of passes, each a loop
over a table. The code mirrors this section; each kind keeps its specifics in
its own section (its block, its verb).
### The tables
| Table | A row is | Its columns | Made |
| --- | --- | --- | --- |
| `places` | a thing on screen a relation can end on | id; its kind (`slot`, `reg` row, `insn` row, source `line`, a `bytes` run, a node, a cell, a pill, a loupe's row, a shelf's tag, a bubble); its address, memory or code, where it has one; its box; its panel; shown, or off its window above or below and how far | one pass over the panes' visible rows, when the moment or a window changes, then kept |
| `values` | a value on screen that may be an address | id; the place it is shown in; the value; its region (stack, heap, code, data, none); its hop in its chain | one pass over every chain, field reading and annotation on screen, with `places` |
| `events` | what the step does | its kind (fire, read, write, register set, push, pop, call, ret); its place; its frame in the step | from the recording's step |
| `kinds` | a kind of relation | the table below | the catalogue's, fixed |
| `knobs` | a kind's setting | the kind; `off`, `step`, `standing` (or its own values); the beat's `emphasis` | from the scene file, per scene and per beat |
| `relations` | a relation found | kind; source place; target place; state (`quiet`, `standing`, `active`); priority; lane; its verb's frames | the resolver's output, per moment and window, cached; a frame between moments interpolates its verbs |
A relation never reads a panel's layout: it joins places. States: `quiet`
(found, not drawn: its echo and the names say it), `standing` (60% toward the
page while a beat lasts), `active` (full ink, for the step that causes it).
### The kinds
| Kind | Says | Join (source ⋈ target) | Knob · default | Priority | Ink, form | Route | Verb, timings |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `thread` | this line is these instructions, and the machine is here | the current `line` ⋈ the `insn` rows of that line | none · always | 0: never gives way | gold, 3; a `tie` bracket on the line and on each run | the left margin, x 54 (on the map, the gutter at x 1008) | standing; moves with `advance` |
| `link` | this register now points at that | a struck `reg`'s value ⋈ `places` by address, where the target has a pin lane (a node, a slot) | `link`: `off`, `step` · `step` | 2 | the target region's ink, 3; a filled head; the pin rides it | the gutter's left lane up into the band, the right lane down to a slot | `link`: s+6, 24 f (36 over 400 units), back 18 |
| `projection` | these bytes are that part of the drawing | a read or write `event`'s run ⋈ the drawing's part made of those bytes | `projection`: `off`, `step` · `step` where a lens with a view is up | 3 | the mark's colour, 2; a bracket at each end | the gutter's right lane; a lens's top or bottom lane | `project`: bracket 6 f, line 18 (30 over 600), back 18 |
| `aim` | this word holds the address of that instruction | `values` of region code ⋈ `insn` rows (or a graph's pills) by address | `aim`: `off`, `step`, `standing`, `drawn` · `off` | 4 | code's ink, 2; a filled head 10 by 10; the row's address framed | the gutter's left lane, x 950 | `aim`: after its word's mark, 18 f (24 past ten rows); glide 24 to a new row; fray 12 + 18 |
| `carry` | this value went from there to here | a load, store, push or pop `event`'s source ⋈ its destination | `carry`: `off`, `arrow`, `value`, `after_touch` · `off` | 5 | primary, 2; an open chevron | the gutter's right lane, x 962 | `carry`: after the source's read, 18 f (24 past eight rows), back 18 with the strike |
| `touch` | this instruction reads or writes that word | a read or write `event`'s `insn` row ⋈ the `slot` by address | `touch`: `off`, `step` · `step` under `annotation = .tied` | 6 | the mark's colour, 2; a head on the stack's rule | the gutter's middle lane, x 956 | `touch`: 12 f (18 past six rows), before the word reacts; back with the advance |
| `arc` | this word points at that row of its own panel | `values` in a panel ⋈ `places` in the same panel by address | `arcs`: `off`, `standing` · `standing`, active in the step that writes or reads it | its panel's: lanes, not the frame's budget | the target region's ink, 2, 60%; full when touched | the panel's left lanes (three; the stack two) | `arc` |
| `stem` | this text speaks of that | a bubble ⋈ the row or tag it is level with | `stems`: `off`, `rest` · `rest` in the [column](#column) | rests only: never with a step's lines | `dim`, 2 | across the gutter, level | in 12 f with the bubble, back 12 f with the fire |
| a loupe's stem | this loupe is the memory round that pointer | a loupe ⋈ the hop it opened from | with the loupe, the author's beat | 1 | the region's ink, 3 | none: straight, over the row's empty end | `open`, `close` |
| a dump's place | these bytes are there | a dump's rows ⋈ a band of [`segments`](#segments) | with `segments`, the introduction's | standing | stack's ink, 3, 60% | over the stage's top, y 56 | the chart in motion.md |
| `echo` | these are one event | two places marked by one `event` at one frame | none · always | no line | the mark itself | none | the mark's |
| `pin`, a `call` span, ink and digits | these are one thing | places whose address is a value shown (a pin); a frame's words (a span); any two places of one address | none · always | no line | on the target | none | `travel`, the span's |
### Which kinds are on
A kind is on by default only where it says what the step did, at the
machine, where the eye already is, and the frame would mislead without it:
the thread, the link, the projection, the arcs, the touch under `tied`, the
column's stems, and the kinds that draw no line. Every kind that adds a
reading of its own (where a value went, where a code pointer leads, which
memory a loupe shows) is the author's to switch on, for a scene or a beat:
`carry`, `aim`, a loupe's stem, a dump's place. **No kind is ever drawn
because the budget has room for it**: the budget only removes.
What a scene writes, for the scene or from a beat on:
```zig
s.relations(.{ .aim = .standing, .carry = .arrow }); // the scene, from here on
cur.beat(s, .{ .relations = .{ .touch = .off }, // this beat only
.emphasis = .aim }); // and what it is about, first in the budget
```
### The resolver
Six passes, each a loop over a table, in this order:
1. **Candidates.** For each kind whose knob is not `off`, its join: values
against places by one lookup each in the moment's address index (`aim`,
`link`, `arc`, pins, ink and digits), or the step's events against places
(`touch`, `carry`, `projection`, the active state of any kind). Out: rows of
`relations`, `quiet`.
2. **Knobs.** Each row takes its state from its kind's knob for the beat:
`standing` where the beat stands it, `active` where a step's event causes
it, else it stays `quiet`.
3. **Priority.** Rows sorted: the thread; then the kind the beat names as its
`emphasis`; then the kinds' priorities; within a kind, the step's order.
4. **Budget.** Rules over the sorted rows: the thread always; at most **two**
active rows that cross panes (three lines in the frame with the thread); at
most **one** standing row that crosses panes; stems only in a rest with no
active row; in a panel, its lanes. Rows past the budget go back to `quiet`
(their echo is the mark), the last first. A touch and a carry or an aim
leaving the same word are one gesture: the touch draws back as the other
leaves, and counts once.
5. **Route.** Per channel (below), rows sorted by span, lanes given greedily,
the longest outermost, nested spans inside one another; a row that cannot
get a lane without crossing another, or a standing one, goes `quiet`. A row
whose target is off its window gets the stub (below). Labels are never in a
channel, so no route crosses one.
6. **Draw.** Each row's verb at its frames: drawn in, held, drawn back,
interpolated per frame from the cached rows.
**Off the window.** A relation whose target is outside its panel's window
comes along its lane to the panel's nearest edge and ends on the panel's rule:
a head pointing out of the panel, and beside it in faint mono 20 how far the
target is (`12 rows`), or, for code, the name of the row (`main+50`). The
stack's and a dump's windows scroll to a word a step touches before its
relation draws; the disassembly's window never moves for a relation (it
follows the pc). Where the target is in no pane at all, no line: the value's
name carries it.
**The map and the minimap.** On the map, where places are thousands, the
thread and each panel's own arcs (standing, lane-capped as above) are all
that is drawn: a step's relations are told in the working frame. A minimap
draws no relation; an arc's end and an aim's target row are its marks, a
1-unit tick in their ink.
**Cost.** Bounded and small, on the map as in the working frame, nothing
scanned once per relation: `places` and the address index are built once per
moment and window; candidates are one lookup per value on screen and one per
event, so the cost is the places and values on screen, never their product;
only kinds whose knob is on are joined; routing is one sort per channel; the
result is cached per moment and window position. The measure: on the map
(some 4,000 places, 6,000 values) the six passes within 1 ms at 60 frames a
second; in the working frame a tenth of that.
`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.
### 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 |
| the gutter's right lane, x 962, between the stack and the registers | a carry: up from a word to a register, or down from a register to a word, both in the state column; its legs into the panels are level with the rows |
| the gutter's middle lane, x 956 | a touch, from a row of the disassembly to a word of the stack, within the height the two share (under the registers, so it never meets a link climbing into the band); where a link down to a slot holds the right lane over the same rows, the touch gives way to its echo rather than cross it |
| the gutter's left lane, x 950, within the context's height | an aim: from a word in the state column across to a row of the disassembly; its legs level with the word and with the row, the head on the disassembly's right rule. In the column form, between a pane and the panes over it, the same lane, its head on the upper pane's right rule |
| a lens's bottom lane, 8 above its edge | what arrives from below: a link to the pin under its node; a projection to a call node |
| a lens's top lane, 4 under its tag | a projection from the view, to the bracket over its node's address |
| a panel's pin lane | a link's last leg to a `row` pin, or its stub |
| the disassembly's call lane, x 14 | a descent's call lane, down from a waiting row to its callee's head; the crossing, down to the kernel's window, and the kernel's answer back up it |
| none | a loupe's stem: from its pointer straight to the loupe, over the row's empty end, or the gap between a loupe's row and the loupe it opens |
Ties that climb from the state column take the left lane and arrive from
below; the view's projections keep to the band in the right lane and
arrive from above; a touch keeps to the context's height in the middle. 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.
**The carry.** A scene says `carry = .arrow` to draw the value's way
between memory and the registers; it is `off` unless a scene asks. Off by
default because at -O0 nearly every step is a load or a store, and with the
`touch`, the names, the offsets' digits and the strikes the move is already
said: the carry is for a scene whose subject is where values go (the calling
convention, the arguments of a call made, a value read back after a
`syscall`), or a beat that names it. Register to register (`mov rax, rdi`)
nothing is drawn: both rows are in one panel, and the strike says it. A
narrower access (a 4-byte load of a word's high half) draws the same arrow;
the source's read frame covers the bytes read, as the `width` cells of the
operand say. A source or destination out of its window: the window scrolls
first (the stack, a dump), or the arrow ends in a stub on the panel's rule
with a count, as a link's does; a folded register (`quiet`) takes it on its
cell. A second value, `carry = .value`, sends the value's digits along the
arrow on a chip of `raised`, landing as the destination's strike: for the
one walked load where the viewer first learns that a register can hold
what memory holds; never in a scene's ordinary steps
([mock 56](mock/56-carry.png)). A third, `carry = .after_touch`, draws a
store's touch first and then its carry, the row naming the word before the
value goes there: for the introduction's `push rbp`, where the push is the
lesson ([motion.md](motion.md#a-word-touched)).
**The aim.** Off unless the author turns it on (`aim = .step` or
`.standing`, for a scene or a beat). On, it finds every value on screen that
is a code address whose row is shown (a disassembly row, a descent window's
row, a graph's pill holding the address), and draws for the word a step
writes or reads (`.step`) or for the words the beat stands (`.standing`). In a
step, cause before effect: the word reacts first (struck, or framed as read),
then the aim draws from it to its row, 18 f (24 f past ten rows), `standard`
(a touch on the same word draws back as the aim leaves it: one gesture, the
row reaching the word and the word pointing back into code),
and the row's address is framed in code's ink as the head lands; only then
what follows (rsp's pin climbing onto a pushed return address; at a `ret`,
the plaque's jump, which goes where the aim points, the aim drawing back as
the plaque lands). When the word is written again: the new value is code with
a row shown, the head glides to that row (24 f, `glide`) after the strike;
code with no row shown, the head goes to the rule as a stub with the row's
name; no longer code, the aim **frays**: it goes dashed (12 on 8) over 12 f
and fades over 18 f. Standing, it rides its rows when they scroll, and a word
that leaves its window takes it away. `drawn` is a standing aim the beat
itself introduces, with no step to draw it: it draws as a step's does, head
first at full ink (18 f), the row's address framed as the head lands (6 f),
and falls to the standing 60% only when the next step begins (the
introduction's return address, III3 to III4). Route: out of the word's panel's
left rule level with it, the gutter's left lane (x 950), onto the
disassembly's (or a descent window's) right rule level with the row, its head
10 by 10 ([mock 57](mock/57-aim.png)).
**Order.** A tie arrives before the thing it points to reacts: see
[`link`, `project`, `touch`, `carry` and `aim`](#6-verbs). Mock 9 shows the standing ties; 10 and
11 all four; 12 the projection to a call; 21 a loupe's stem; 44 to 47 the
touch, 48 the touch against an echo alone and against a name in the operand; 56 the carry; 57 the aim.
## 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 clock's count ranged right at 1856 | |
| margin | 1032 to 1080 | page |
No data below 888: the caption and the clock's count, which a player's
controls may cover the foot of, and which the narration says again.
**The program column** (left): source over disassembly, in every split:
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; a lens
with no view of its own is its drawing alone, over the program column,
and the state column is the machine's from the top. The split is the one
thing about the layout a scene chooses.
The rows below are for a registers panel of 11 rows (sort's: eight
registers the scene moves, nine folded three to a row); every row the
registers fold more is a slot more of stack (the list's `reverse`, 10
rows: thirteen as the subject), and a scene that folds none (sqlite's
continues, 17 rows) has six fewer. Each pane with a minimap gives it 48
of its width (the strip 40, 8 to the content); the strip's rows are the
map's, 4 units each, so a pane of n rows (its strip 24n + 6 high)
shows 6n rows of its column.
| Split | Drawing | Its view | Source | Disassembly | Registers | Stack | Backtrace |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `none` | | | 14 lines, 48 to 416; strip 84 | 17, 428 to 868; strip 102 | 11, 48 to 344 | 15, 356 to 748; strip 90 | 4, 760 to 888 |
| `beside` | 152, 48 to 200 | 152, 48 to 200: 5 rows; strip 30 | 8 lines, 212 to 436; strip 48 | 17, 448 to 888; strip 102 | 11, 212 to 508 | 14, 520 to 888; strip 84 | in the stack |
| `subject` | 296, 48 to 344 | 200, 48 to 248: 7 rows; strip 42 | 8 lines, 356 to 580; strip 48 | 11, 592 to 888; strip 66 | 11, 260 to 556 | 12, 568 to 888; strip 72 | in the stack; the view of `calls` |
| `blocks` | 344, 48 to 392: `rings` or `layers` | none | 6 lines, 404 to 580; strip 36 | 11, 592 to 888; strip 66 | 11, 48 to 344 | 20, 376 to 888; strip 120 | in the stack |
Each panel is a window onto a column of the [map](#the-map-and-the-minimap),
and its minimap shows where.
**Where the room comes from.** Measured on this round's renders (fib,
list, heap, sqlite, sort, syscalls: every scene in `subject` but syscalls,
in `beside`), the 840 of the state column went to the view (200), the
registers (440) and a stack of six (176); of the registers' seventeen
rows a stepped scene changed six to nine from its first frame to its last
(heap's, whose steps cross `malloc` and `free`, twelve; sqlite's
continues all seventeen), so eight to eleven rows, 190 to 260 units, held
values nobody read while the stack, which carries the frames, had six
slots. In the program column the source showed ten lines of functions of
eight to ten, and the disassembly nine; with the `blocks` lens the
disassembly had become the band's view over the state column, seven rows
across the frame from its source, and the graph (ten layers, 400 high)
panned in a drawing of 296. So:
- the registers fold what the scene does not move ([`quiet`](#registers)):
six rows to the stack, which goes from six slots to twelve as the
subject (fourteen beside, fifteen alone);
- the source is eight lines with any lens up, and its two rows go to the
disassembly: eleven as the subject;
- the `blocks` lens has no view: the disassembly stays under the source,
eleven rows; its drawing, the [graph](#graph) as `rings`, has the
squarer pane a ring wants over the program column (880 by 344, where
sort's eleven blocks and both loops are whole, 732 by 286, nothing to
pan), and the state column, with no view to hold, is the registers and
a stack of twenty.
The band, the caption band (192 with its margin: what a player's
controls cover) and the margins are as they were; nothing else gave.
| Of the frame | `none` | `beside` | `subject` | `blocks` |
| --- | --- | --- | --- | --- |
| context | 69% | 56% | 48% | 54% |
| of it, the registers / the stack | 18% / 24% (were 28% / 14%) | 22% / 28% (were 33% / 17%) | 26% / 28% (were 39% / 15%) | 23% / 40% (were 33% / 13%) |
| lens band (the drawing and its view) | | 13% | 21% | 15% (was 21%, the disassembly its view) |
| caption band | 10% | 10% | 10% | 10% |
Three layouts were weighed ([mock 42](mock/42-frame-layouts.png)): **A**,
this one; **B**, every register a row and every chain whole, the source
at six lines to give the disassembly thirteen, which leaves the stack at
six; **C**, the registers in two columns of eight (440 each, every chain
cut to a hop and `more`), which gives the stack fourteen but takes the
telescopes from the registers that move. A keeps the chains that are
narrated and gives the stack and the disassembly the most that the
narration uses; the folded values are still on screen, and whole on the
map.
### Direction and nearness
**Which way things go.**
- **Down is deeper.** Under each thing in the program column is what it
becomes: the idea (the band) over the source, a line over its
instructions, a call over its callee ([`descent`](#descent)), the
program over the kernel. In the state column the registers are over
the stack. A call goes down and a return comes up; in the backtrace and
the calls tree the newest is lowest.
- **Memory is where it is.** A dump, the stack and a loupe are in address
order, low on top, because a row's place there is its address: so the
stack's newest frame is its panel's top, and an arc or a jump's line goes
whichever way the addresses do. It is the one exception.
- **Execution goes down and across; meaning comes back up.** A step's
cause is a row of the program column. Its effects cross the gutter into
the state (an instruction to the register it writes) and go down it (a
register into the stack); what they mean climbs into the band (from the
stack up the gutter, from a register to a pin under a node) and crosses
back to the drawing from the bytes beside it. An answer comes back up
the way its call went down: a return to its call row, the kernel's answer
up the crossing lane to the `syscall` row, then rax.
- **A still is read the other way, top down**: what it means first, then
how it is made. The band is on top because the idea is what a scene is
about.
- **Every tie runs one of those ways.** In the context down or right (the
thread, a link to a slot, a loupe's stem, the call lane and the
crossing, a touch: across the gutter, its leg in it going to its word's
height whichever way that is, since the two columns are one level, the
machine); into the band up, then left (a link to a pin, a projection).
None runs against them.
**What sits together.** Things that act on each other are neighbours,
each pair in one place:
| Pair | Where |
| --- | --- |
| a line and its instructions | the source over the disassembly; the thread between |
| an instruction and what it changes | the change in its own row's annotation; the register across the gutter |
| an instruction and the stack word it reads or writes | across the gutter at about one height (layout A puts the disassembly and the stack level); the word's role is the annotation's name, its offset the operand's displacement; a walked step's touch between them |
| a pointer and its target | the target's pin; in one panel the `arc`; a `loupe` hung under the pointer |
| a call and its callee | the callee's window under the call row ([`descent`](#descent)) |
| a system call's arguments and the kernel's side | the arguments under the `syscall` row, the kernel's window under them |
| the drawing and its bytes | side by side in the band, the projection across the gutter at one height |
| a call tree and its frames | the tree and the backtrace beside it, both down to the newest; a frame's span on the stack |
| the flags a compare sets and the jump that reads them | their two rows, framed together while the jump is current |
**The audit.** Against these rules, what moved:
| Where | Was | Now | Why |
| --- | --- | --- | --- |
| the `blocks` lens | the disassembly moved over the state column as the band's view, seven rows; the source alone in the program column; the graph in boxes and square lanes over the program column, panning | the disassembly under the source, eleven rows, the thread in the margin; the graph as rings over it, whole | a line over its instructions is a pair, and the thread had crossed the frame; a loop drawn as a ring is the thing that comes round (mocks 25, 43) |
| the graph's counts | the layout by the whole recording's counts (the hot path straight down), the edges the whole run never takes dashed, the blocks it never reaches folded from the start | the layout from the code; counts so far; what is not reached yet quiet until it is | a picture of a moment holds nothing from after it ([Forbidden](#composition)) |
| the registers | seventeen rows, always | the scene's own as rows, the rest three to a row (`quiet`) | the room went to the stack, which carries the frames the scene is about (mocks 40, 41) |
| the `syscalls` lens | the kernel's side, on vellum, in the band over the program | the kernel under the `syscall` row, the descent's floor; the band holds the calls so far as strace writes them | the kernel is under the program, and a call's arguments and the kernel's side are now neighbours (mock 14) |
| the backtrace: a panel, the calls lens's view, the backtrace lens, the map | newest on top | newest at the bottom, `#0` last | a call goes down: it reads as the tree beside it does, and the backtrace lens's `#0` sits over the source line it is at (12, 13, 19) |
| a call followed into a function | the window went to the callee; the call row left the screen | the `descent`, when the scene follows the call | the call and its callee are neighbours, and the return has a row to come back to (16) |
| `qword ptr` and its kin | in every operand | gone; a `width` where no register says the size | the operand is shorter and the width is shown only where it is news (17) |
What stays, and why:
- **The band's view over the registers.** It is memory over the CPU,
against down is deeper; but under the registers it would be 300 units
from the drawing made of it, and the projection between them would cross
the frame. The band is the idea twice, as drawn and as bytes, and the
drawing and its bytes being side by side matters more.
- **The registers beside the disassembly**, not under it: an instruction
and its register are across the gutter at about one height.
- **The map** keeps the frame's order across its four columns: the drawing
and the source, the disassembly (a descent whole, the kernel at its
foot), memory over the registers, the stack. The backtrace stays at the
foot of the first column, beside the disassembly it is the chain of.
- **The lenses**: a list left to right in list order, an array by index,
a tree down, the far view's time left to right, a loupe hung under its
pointer. None goes against the rules.
### segments
The address space to true scale, for its size, and each end enlarged once
until its parts can be named. High addresses on top, as the textbook draws
it; 0 at the foot. No rulers: the whole's two ends and the edges of every
named band carry their addresses, and the bands their sizes.
| Part | Drawn |
| --- | --- |
| the whole | the user half, `0` to `7fffffffffff`, in a bar 20 wide the stage's height (mock 34: 72 to 864), framed 2 in `dim`. Its ends' addresses and its size (`128 TiB`, at its middle) in mono 20 `dim`, ranged right 12 left of it; nothing else. Every mapping is where it is, which at this scale is a 2-unit line in its ink inside one end: the stack, then the libraries 128 MiB under it, at the top; the heap over the program, 16 MiB above 0, at the foot |
| a cluster | the mappings at one place: the stack; the libraries (libc, ld.so, its cache, the vDSO); the program and its heap. Each is enlarged once, and only once |
| an enlargement | the cluster from its lowest start to its highest end, linear: a box 180 wide (108 in a column of 880), framed 2 in `dim`, 2 out; the boxes' left edges on one x, in address order down the stage, about 48 apart, each as tall as its names need (mock 34: the stack 72, the libraries 368, the program and its heap 252). A mapping is a band in its ink 30% over the page; touching mappings of one file and one permission are one band; between two bands of one file a 2-unit page line where both are 6 tall. What is not mapped is page: the 1.3 MiB between libc and the loader is as empty in the box as it is in the process |
| the magnification | two 2-unit `rule` lines from the cluster's line on the whole (at its right edge) to the box's left corners. Nothing else is drawn between the whole and the boxes |
| the names | right of the box, from 64 past it (the leaders' room). A row for each edge of a named band: its address in mono 20, in the ink of the band it bounds, and a leader (2, `rule`) from the edge, 8 out, straight to 20 short of the address, 12 in. Between two edges a row for the band, indented 24: its permissions and its size (`dim`, ranged right 132 in), and its file in primary at 252 (`[stack]`, `libc.so.6`); a file of several named bands once, on a `quiet` bracket over their rows. Rows 24 apart, each as near its edge as the others let it (crowded rows pooled round their mean), inside the box's share of the stage; a leader never crosses another, as the rows keep the edges' order |
| what is named | the program by segment: each of its mappings a band with its two addresses, permissions and size, under a bracket with its name, because the scenes point into them (its code, its data). Every other file once: its mappings as one (an anonymous mapping after a file's data, its bss, with it; the vDSO with its data), its start, stop, size and name, its permissions where they are one (`rw-` for the stack and the heap), and where they differ, each part's written inside its band, centred, where the band is 28 tall. A band under 6 tall is drawn and not named (an anonymous page; in mock 34 the vDSO) |
| live | rsp an `under` pin in the stack's band (rbp's name on it where rbp is in the same pixel, names keeping their sides); rip a row pin at the end of its band's row (`◂ rip`). Each comes on its beat with its register's value framed as read and its band and the band's row framed (`ink`'s echo), and stands while `segments` does. In the introduction's first chapter neither: there are no registers yet; its second brings them (II2, II3; mock 58) |
| a dump's place | in the introduction, where the dump the scene has built stands beside it: a `tie` bracket on the dump's rows, and a [`link`](#4-ties) in the stack's ink from the bracket's top, up into the stage's top margin (y 56), across, and down onto the stack's box at the dump's address, its head on it. It draws in its own beat (the dump's addresses take the stack's ink as its head lands, never before) and then stands, quiet (60% toward the page), while both are on screen. For a camera's visit, where the dump is still far thinner than a unit, its place is marked on the box: a 2-unit tick across it in the stack's ink at the dump's address, the dump's size over it (`128 bytes`) left of the link's head |
| `ink`'s echo | the band a word points into, framed as read inside the box (2 units, 4 in from its sides, 6 over and under the band), and that band's row of names framed with it |
The physical comparison is the caption's, worked from the recording: if
the bar were the Eiffel Tower (330 m), everything mapped would be 7 µm, a
tenth of a hair, split between its two ends; the introduction's 128 bytes
would be 0.3 nm, about an atom.
Three treatments say less and less (mock 35): **A**, this (mock 34);
**B**, every file once, the program too, and no pins; **C**, the whole
alone, each cluster one label at its end (where it starts, its size, its
name). A is the default: the program's segments are what the scenes point
into, and every other file is said once. `segments` is a frame of its own
(mock 34) or, in the introduction, the program column (mock 30, the boxes
108 wide). In motion each box rides out of its line along the
magnification ([`enlarge`](#6-verbs)).
### aligned
The source with the instructions it compiled to, in one panel with one
tag, each line level with its code. A split a scene chooses, the default
nowhere: the panel spans both columns (1792), the band and the state giving
way while it lasts. It has two forms, and a scene names the one it wants:
- **`interleaved`** (mock 33), as `objdump -S` prints it: each run of a
line's instructions is a group, its head a row with the line on `raised`
paper, its rows under it, indented one step under the line's text. Lines
and addresses share one place column (ranged right at 196: `21` over
`1001926`): both say where.
- **`columns`** (mock 36): the source on the left and its instructions on
the right, a 2-unit `rule` the seam, 48 after the longest line the window
shows, so that the two stay close. A line stands level with the first row
of its run, its cell as tall as the run, its first row on `raised` paper
(the head of `interleaved`, beside its rows instead of over them). Each
column begins with its place, ranged right 132 into it in mono 20: the
line's number in the one, the instruction's address in the other: one
slot, one face, one distance in, so the two read as the same kind of
thing.
In both a 2-unit `rule` across the panel over every group marks where a
line's code starts and ends; nothing alternates. The grouping is the
thread.
| | `interleaved` | `columns` |
| --- | --- | --- |
| a run of one row; of many | its head and its rows, never folded in the working frame | the line beside its first row, its cell as tall as the run |
| a line's second run (a `for`'s step, a `while` tested again after its body) | its head again, on the page, faint, `again: its second run` | the line again in its cell, on the page, faint, `again: its second run` |
| rows of no line (padding, a function without source) | a faint head with the function's name, `_init · no line` | the cell empty but for `_init · no line`, faint |
| a line with no code of its own | no group: the gap in the numbers says so | in source order after the line before it, faint, the instruction cell empty, `no code of their own` on the first of a run of them: the source column reads as the file does |
| the pc | its row's wash and plaque; its line's number the gold plaque in its head | its row's wash and plaque in the instruction column, the wash across both where it is its line's first row; its line's number the gold plaque |
`interleaved` reads down one listing and puts each instruction right under
its line; `columns` keeps the source readable as source, at the cost of an
empty cell under a long run. Reach for either to teach what a line compiles
to, in the introduction, and in a pair (a `pair` puts the source in the
middle and each build's rows aligned to it on its side). `align` and
`stack` change between `aligned` and the stacked form, and between its two
forms; it scrolls as one. Mocks 32, 33 and 36.
### pair
Two runs of one program seen against each other: two builds (plain and
with AddressSanitizer), two versions, two C libraries, two inputs. It is
a split of the working frame, and general: the shared panels are drawn
once, the ones that differ twice, one on each side of a seam.
| Of the frame | Drawn |
| --- | --- |
| the seam | the gutter between the columns (944 to 976): the left column is one run, the right the other, each panel's tag naming its run (`plain · disassembly`, `asan · disassembly`). Down is still deeper in each; across the seam is the other run |
| the source | shared when both runs are the same file: one panel across both columns, 1792 wide, five lines (48 to 200). Each run's current line is marked on its own side of it: the left run's gold plaque on the number at the left, the right run's ranged right at the panel's right edge, the wash across the row once when both are on it. Two files: two panels, as below |
| each column | its run's context cut to what the scene's line touches: its disassembly, nine rows (212 to 460); the registers the line reads or writes and rip, rsp, rbp, four rows (472 to 600); the frame, ten rows (612 to 884): the stack panel's words, or, where the scene's stores are bytes (an overflow), the frame as bytes ([`hexdump`](#hexdump) `eight`). A run built with ASan adds the shadow to its frame's rows. A dump of ten rows is the stack panel's height, so the four registers and the nine instructions keep their places and nothing gives |
| alignment | the two disassemblies are scrolled so that the current line's first row is at one height on both; below it each runs on. The two frames are scrolled so that the same variable's first row (`buf`) is at one height: then what lies past it faces what lies past it (plain's saved rbp and return address, ASan's redzone). Rows the alignment shows that hold no field are loose bytes. Corresponding things face each other across the seam |
| only here | a row one run has and the other has not (the instrumentation; a function only one build calls): a 4-unit `dim` bar on its seam-side edge. Its counterpart is the page facing it, or nothing |
| differs | a value that differs from its counterpart at the same step (the saved rbp kept on one side and overwritten on the other): a 4-unit `bright` bar on its seam-side edge, on both sides. It is the difference across runs; a strike is a change in time, and both can stand together |
| the clock | one rule, counting the pair's steps; under it, ranged right, each run's moment: `plain moment 61 · asan moment 412` |
| the caption | one, for the pair: it narrates the difference |
| the minimaps | each pane's own, as anywhere, its run's column; the shared source's at its right end. The map is one run's at a time: a `surface` goes to the side in focus |
**Keeping the two in step.** A pair's step is one source line in both
runs, or one turn of a loop when the narration says so: the unit both
share. Inside it each side walks its own instructions; their cascades
share the levels (CPU, memory, the idea), and the side with more rows
sets the step's length, its rows 6 f apart, the other side's spread over
the same time. Its first time through, a row only one run has (ASan's
check before a store) is walked row by row as any step, the other side
holding still with its plaque on the row that faces it; after that, at a
run inside the step. When one run stops (a report, a crash, an exit) and
the other goes on, the stopped side holds its last picture, unveiled,
and the steps go on in the other alone.
**When they part** is the scene's point: the first step in which the two
runs do different things (one stores, the other branches to a report).
That step is walked; its two sides' first different rows are framed
`attention`, one each side, and nothing else moves until both have
struck. What one run then does alone, if it is the harm the other
prevented, is walked too, never at a run: in the ASan scene, the plain
build's return address overwritten a byte a step, its reading turning
stranger each time, the half-written word held under its own caption
while the other side stands stopped on its report (mock 38, the scene's
poster).
A run that writes to stderr (ASan's report) shows it in its own column, in
place of its registers and its disassembly's lower rows once it has
stopped: a panel of the run's output, its lines as written and cut at its
edge with `…`, the words the narration names framed bright (mock 38). Its
disassembly keeps the rows down to the call that stopped it, which reads
`never returned`; its frame keeps its last picture.
Mocks 26 to 28 and 38; [the scene](motion.md#a-scene-asan-against-a-plain-build).
### 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 with their chains (the quiet ones
too, which the working frame folds), 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 box is as tall as its
rows, never taller**: a dump is the rows that hold a field or were
touched, with `more` rows for the rest, so a region with six rows of
fields is a box of six (176 units), not a window of 32. Space a column
has left is given, in this order, to: more of the stack (before it folds
into `more`); the memory round the pointers the registers and the
stack's words hold, a short dump each (five rows round the target, its
region's ink, under the memory panel); the loupes open; and last the
map's key (the scene, the moment, the marks' legend, three rows). Only
then is a column's foot 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, up to 32 rows
round what was touched, as many as hold something, fieldless rows
folded. The drawing: its size in the frame (its subject size, 880 by
296; the `blocks` lens's 880 by 344, the disassembly column linear
beside it). 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 a pane's own: its whole column of the map, small, in a
strip inside its frame at its right, the way a code editor shows a file
beside its text. Every pane that shows less than its column has one: the
source, the disassembly, the stack, a dump (the band's view, a hexdump
panel), a backtrace longer than twice its window. The registers have
none (every register is on screen; the quiet ones' chains are on the map,
a column the strip would only repeat); a lens's drawing is whole and has
none; a loupe
has none (it is held over the frame for a step or two, and its tag says
what it is).
| Part | Drawn |
| --- | --- |
| strip | 40 wide, inside the pane's frame at its right, 2 in from the rule, over its body (under the tag), on `well` (`101a48`). The pane's content keeps 8 from it: a pane with a strip has 832 for its content, the frame and tag still 880 |
| scale | fixed: a row of the map is 4 units (a stroke 3 high, 1 between), a row's 880 units 36 (a character two thirds of a unit). A column that fits is drawn whole from the strip's top; a longer one shows the rows round the pane's window, the window in the strip's middle and the strip clamped to the column's ends, with three faint dots at an end where it goes on, and it scrolls with the pane |
| rows | each run of text a stroke from where it starts, as long as it is, in its ink 65% of the way from the page: the file's indents and lengths; the disassembly's address, mnemonic, operands and a call's name; the stack's chains in their inks; a dump's bytes and readings. No text: at 4 units a row none could be read |
| window | the rows the pane shows, framed 2 in primary across the strip: the brightest thing in it |
| marks | at the row's left, 4 by 4, in this order: the current row gold (the pc's in the disassembly, the line's in the source), a strike vermilion, a read in read's colour; held a vermilion 2 by 2. An `arc` with an end off the window: a 2-unit line in its ink down the strip's left edge between its two rows. A block's first row (a graph's, shown linear): a 2-unit `rule` tick at the strip's left |
It says where the window is in the whole (the line in the file, the
function among its neighbours, the frame in the stack, the node's row in
the heap), and what happens outside the window. A mark outside the window
is on the minimap and nowhere else: when the step strikes a word the
stack's window does not show, its row on the minimap strikes with it and
`flash`es 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:
every change on it starts 6 f after the primary onset it follows, never on
that frame. Its window glides with the pane's `scroll`, and grows or
shrinks with its pane in a `relayout` (the same 48 f). Every change
between a column seen whole and the pane's window on it is a move the eye
follows, never a cut:
- **A far jump in the same column** (a `continue` to another loop, a
return to a caller in view, the stack's window to another frame), at a
walk: the pane `unroll`s to its column, the window travels to its new
place along it, and the pane `roll`s back in there (96 f in all), the
mark lighting gold at its new row on the way. At a run, where 1.6 s is
too long: the new row lights on the strip, the strip's window glides to
it (24 f), and the pane fades through (12 out, 12 in), the strip having
shown where it went first.
- **A jump out of the column** (another function, another file) is told
on the map, `surface` and `dive`, as a far `continue` is; the strip
fades through with the pane only at a run.
- **"The whole function", "the whole stack"** for a beat, in the frame:
`unroll` and `roll`.
- **`dive` and `surface`** squeeze each column into its strip and back,
the window's outline riding on it (above); **the sprint on the map**
keeps the windows gliding with the pc, so the dive after it starts from
where the eye already is.
**What it costs**, measured on the rows the videos draw: 48 units of each
pane's width. The source's lines are cut four characters sooner (at 63 in
place of 67). The disassembly's annotation starts at 540 in place of 564,
so its room loses 24, not 48: `1004098 → 1004070 ← 9` stays whole, and
operands longer than 23 characters push it right as before. The stack's
roles and spans move 48 left and its chains end 48 sooner (one hop fewer,
then `more`, where a chain was long: `sqlite3VdbeExec+189…` is cut four
characters sooner). A dump's reading is cut 48 sooner, its pins 48 to the
left (`malloc's: a chunk of 32` still whole). The registers lose nothing,
and the registers carry the longest chains.
**In the other forms.**
- A [`descent`](#descent): one strip for the panel, the column of the
deepest window's function (the pc's), its window framed; the callers'
windows are other functions and not in it. A `descend` or `ascend`
fades the strip through (12 f) as the new window opens.
- The [`graph`](#graph) and the `blocks` lens: the lens's drawing is whole
and has none; the disassembly under the source keeps the linear
column's strip, each block's first row ticked.
- [`aligned`](#aligned): one strip at the right of its 1792 panel, the
listing's whole column, a row of the listing a row of the strip; in
`columns` a row's two cells side by side, at the one scale.
- A [`pair`](#pair): each column's panes their own strips, and the shared
source its one.
- A [`loupe`](#loupe): none of its own; the pane it lies over keeps its
strip, covered where the loupe covers it.
**The corner minimap is gone.** The working frame carried the whole map at
a twentieth in the caption band's corner (192 by 108): a column was 44
units wide there and a row 1.2, and nothing in it could be told apart.
The map stays the picture of everything at once (a scene's opening, a
sprint, a far `continue`); in the working frame each pane carries its own
column at a size that reads, beside the rows it is the whole of, and the
`dive` makes each column into its pane's strip. The caption band is the
caption's and the clock's.
### 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 1856. 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".
A scene in chapters has one clock for its one recording, counted from the
recording's first stop and only forward; it comes with the first thing on
screen that shows a moment's state of the CPU (the introduction: its
registers, II2), and before that there is none. Its **label**, ranged
right 24 left of the count (alone, at 1856, where there is no clock
yet), is the chapter: its numeral and name, Go 18, `faint`
(`II registers`), crossfading at each seam (12 f, secondary): where in
the video, as the count is where in the recording.
- **`chapter`**: a part of one scene with a title of its own, opening on
the last picture of the part before (the introduction's four). Its title
is said, not carded: in the caption's place, one line, Go Medium 40, its
numeral `faint` and its name `bright` (`II Registers`), up its reading
time as a caption is, over the picture, at the chapter's seam
([`title`](#6-verbs)); its name stays as the clock's label. A chapter
ends when its last text is read; it holds no 2 s of its own, the seam is
its close. The video's chapter marks are its titles' frames ([mock
62](mock/62-seam.png)).
- **`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); in a scene in chapters the first chapter's title comes first (0.1 to 2.6 s) and its first text after it, and the first step still fires by 4.0 s |
| changes | only in a rest, never under a moving thing |
| names | only what is on screen at the pace it plays: no register a run veils, no step that has not happened or that played more than its 60 f lead ago; and nothing before it has been shown, in a caption or a label (a dump's header, a tag): the introduction's first bytes are `128 bytes at 7fffffffebc8`, not the stack's, until the stack is on screen |
| checked | by the instruments' CAPTION ([motion.md](motion.md#the-instruments)) |
| 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. A chapter's title is not one: it is
said over the picture it grows from.
- **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.
### column
The second way to compose a scene, beside the working frame, which stays the
default where a scene chooses nothing. The working frame shows the whole
context with a caption under it; the column shows the panes a beat is about
in one column and says what they do beside them, level with where they do it
([a scene built this way](motion.md#a-scene-in-the-column-open-followed-down);
mocks 49 to 55; the renders `column-1080` beside `syscalls-1080`, and
`column_sort-1080`). It is an author's instrument: the scene says for every
beat its form, which panes stand, where its text sits and what it is tied to;
the defaults below only spare typing, and never decide against what the scene
wrote.
**When to reach for it.** When the story is a column of rows that goes down
and comes back: a call followed down to the kernel and back up, a recursion,
the stack growing and shrinking, a frame filling byte by byte, a loop told
turn by turn beside its rows. There the text, level with its row, moves as
the story does, and the panes the beat needs get the height (a descent of 24
rows where the working frame gives 17). **When the working frame serves
better**: when every step acts on the program and the state at once (sort's
swaps with the array, the heap scene's nodes over their bytes, a `continue`
whose registers all change), when two runs face each other (the
[`pair`](#pair)), and for a scene's opening and close, where the whole
context is the point. Most scenes mix the two.
**Mixing them.** A scene in the working frame takes the column for a few
beats and comes back; the change is made in a rest, between beats, in one
order and never in one frame. Into the column: the caption leaves (12 f); the
panes the column will not keep fold to their tags where they stand (rows out
6 f, then the panel closes as its tag travels to the shelf, 18 f, `glide`),
so that no panel ever crosses another, empty or not; then the panes that stay
glide and resize to their boxes (24 f), their rows riding with them; the
text column opens and the first bubble arrives (18 f). Back to the working
frame: the bubbles leave together (12 f); the panes glide to their working
frame's boxes (24 f); the folded panes unfold from the shelf in their places
(18 f, rows in 6 f); the caption arrives. About 70 f each way. A part with
no panel round it (the introduction's dump: a header over its rows) folds by
its own rows: they glide up into its header (24 f, `glide`), the header
becomes the tag where it stands, and the tag slides to the shelf (24 f,
`glide`); back, the reverse. Nothing goes out in a few frames. A drawing that
changes size between the forms keeps its labels inside its box at every frame:
it scales as one (24 f) and its tag's note crossfades if it no longer fits.
**The frame.** Two columns of 880, the working frame's own: the panes on the
left (x 64), where the program column is in the working frame, so that a scene
going between the two keeps its source and disassembly where they were; the
text on the right (x 976), as an assembler's comment and the row's annotation
sit right of the code they speak of. While the program column has nothing in
it yet (an introduction building the state first, each part in the place it
will keep) the text may stand on the left instead, beside the panes on the
right. The gutter between keeps its lanes.
| Part | Where | |
| --- | --- | --- |
| `shelf` | the panes' column, y 48, 24 high | every pane the beat leaves out, folded to its tag, side by side in the frame's order (the drawing, its view, source, disassembly, registers, stack, backtrace). A tag's note says what the pane holds of the beat (`registers rax 3 rcx r11`, `stack main+45 pushed`), and a value struck in a folded pane is struck on its tag, in the frame its row would be: an `echo` of a row not drawn. Nothing is hidden: everything is on the shelf, and folded is acme's own way to keep a window |
| panes | from 84 to 1032, 12 apart, each its block as specified (880 wide, rows of 24) | the beat's panes in the frame's order, the program over what it acts on: source, disassembly (or a descent), registers, stack; the drawing over them all when a lens is in the beat |
| the floor | 888 to 1032 | under a player's controls when it is paused, as the caption band is. Panes run into it, but only with rows that continue a window (the stack's deeper words, the disassembly's later rows, a register panel's folded rows): a row a beat narrates or a step changes, and rip's, stand above 888 |
| bubbles | the text column, 48 to 888 | below |
| `clock` | under the text column, y 900, its count at 1856 | as [`clock`](#clock-and-caption), 880 long |
**Which panes stand.** The author's list, per beat, each with its rows or
`rest`. The default, when a beat names none: the pane of its cause (the
disassembly, or the descent; the source over it, three lines round the
current one, when the beat changes line) and the pane where its effect lands
(the registers for a register, the stack for a stack word or a call's push,
the drawing when the idea changes); the cause's pane gets the rows its window
needs (a descent all its windows, the disassembly 11), the effect's the rest.
Change the panes only where the beat's subject moves to another pane: each
change costs about 1.4 s (the built scene changed them seven times, 9.5 s of
its 23% more), so a column scene of eight beats should change them three or
four times, not at every beat.
**Panes between beats.** What persists slides; nothing appears or vanishes in
one frame. In the rest between two beats, in this order: the last bubble
dims; the panes that leave fold (rows out 6 f, the panel closing as its tag
travels to the shelf, 18 f, `glide`); the panes that stay glide to their new
boxes (24 f); the panes that come unfold (the tag from the shelf as the panel
opens, 18 f, rows in 6 f); then an older bubble in the way glides out of it
(24 f) and the next arrives. Never a fold and an unfold in one place at once.
**A pane that stays and changes height keeps its rows** the whole way: its
frame glides and its window gains or gives up rows at the edge that moves (the
rows it loses fade as the edge reaches them, those it gains fade in behind
it); it is never drawn empty, not for a frame (the built scene emptied its
descent for 40 f while it grew).
**`bubble`.** A piece of narration: Go 40 on 54 as the caption is, code in
mono 35, lines of at most 40 characters (80 for a text `above` a subject
that spans both columns: two lines in its band of 120), 16 of padding, 812
wide at most at 40. The
newest is on `raised` paper, primary: the one being said. An older one loses
its paper and dims to `dim` (18 f, as the next arrives), and stays as the
account the viewer can glance back at. Three stand at most; a fourth's
arrival makes the oldest leave first (12 f, `exit`). All leave at a chapter's
end.
- **How long**: its reading time (90 f + 3.6 f a character) is covered by its
beat: the 60 f lead, the beat's steps and a hold of at most 84 f, so that it
is never still being read while nothing moves (the built scene's 104
characters over a single step left 4.9 s of stillness). For one walked step
that is about 64 characters, two lines; three lines only for a beat whose
steps last as long as they take to read (a run, a crossing, a store at a
time). A held rest the scene means (a poster's picture) is said so, and is
the one exception.
- **Where it sits**: its first line level with the thing it speaks of (the
row's centre on the line's), so that the eye crosses on one line. The
author may name another level; the default is the row of the beat's first
step. Where the newest needs a place an older one holds, the older one
glides out of its way (24 f, before the newest arrives): above it, or below
where there is no room above. An older bubble rides with its row while the
row moves (a window closing round its call row) and stays where it was once
the row has gone.
- **What the position says.** Level with its row, a bubble is where the story
is: down the column as a call goes down, the kernel's lowest; back up as it
returns, the account then lying below it; a loop's turns at one height,
each turn's bubble pushing the last up, stacked as bars are.
- **Its stem**: a 2-unit line in `dim` from the bubble's first line across
the gutter onto the pane's right rule level with the row, a head 7 by 8 on
the rule (the row's own end is the pane's minimap). It draws as the bubble
arrives (12 f) and back as the step fires (12 f): the bubble points while it
is read, and the step's own ties have the gutter while it plays. A bubble
about a folded pane points at its tag on the shelf. The author may give a
bubble no stem; its level is then the tie.
- **The caption's rules, restated**: it arrives (18 f, rising 8) in a rest,
60 f before the step it describes fires (120 f for a scene's first); it is
the newest at most 720 f; nothing arrives, moves or dims under a moving
thing; it names only what is on screen at the pace it plays.
**Placements.** Where a beat's text is, chosen per beat (or per scene):
| Placement | Where | For |
| --- | --- | --- |
| `beside` | the text column; the panes in one column | a subject made of rows, or tall: the disassembly, a descent, the stack, a frame as bytes, the source and its instructions, the address space |
| `below` | the caption band under the working frame (every pane as it is) | a beat that needs the program and the state side by side: a scene's opening, which establishes everything; a `continue`; a step whose effects land in both columns at once; a `pair` |
| `above` | a band of 120 over a wide subject at the stage's top, the subject under it | a wide drawing whose story runs down it (a calls tree growing, a graph in `layers`, the `aligned` source and code): the text leads the eye in at the top |
| `on` | in the subject's own free space | a wide drawing with room inside it (a ring's interior, the corners round the rings, the map's key and the gaps of its columns); tied by a stem to the part it speaks of |
The choice follows the subject's shape (rows: `beside`; wide: `above`, `below`
or `on`), where its free space is, and the way the story moves (text leads:
above when it runs down, below when the result arrives at the foot). A bubble
`on` a drawing keeps 16 clear of every element, every edge's path and every
path a mark will travel while it stands; its stem crosses nothing, going round
the drawing's outside where it must (mock 55); where no such place holds it,
the beat is `above`. The renderer finds the place and checks it from the
beat's steps; a scene does not place it by hand. A bubble never travels
between placements: the last leaves (12 f), the frame changes, the next
arrives (18 f).
**Ties and paces in the column.** The step's ties are the frame's: the
thread, a link, a projection, a touch, a carry. A touch from the disassembly
to the stack under it leaves the row's right rule, goes down the gutter's
middle lane and ends on the stack's right rule, its head pointing left (mock
49). At a run the panes keep their places and only the newest bubble stands;
at a sprint the scene surfaces to the map as ever, and a bubble set `on` the
map is the sprint's caption.
**Reaching the whole context.** Nothing is hidden: the shelf (every pane's
tag, and each change in it struck there); the beats spent on the whole
(`below`, the working frame), a scene's opening and close by default; and the
map and `unroll`, as in the working frame.
**Measures, as built** (`open` followed down, the working frame against the
column at the crossing, mock 54 and the render):
| | The working frame | The column |
| --- | --- | --- |
| the descent at the crossing | 17 rows (main 3, the stub 1, open 8, the kernel 2, heads 3) | 24 (main 5, open 13), up to 27 with its floor above 888 |
| source | 8 lines | 3 |
| registers, stack, the log, its bytes | on screen: 14 rows, 11 words, 152, 152 | on the shelf, a tag each; rax 3 struck on its tag |
| narration | 2 lines of 64 under the stage | up to three bubbles of lines of 40 beside the rows; the newest level with its row in most beats |
| height for panes | 840, shared by seven panes | 948 (84 to 1032), shared by two or three; 144 of it the floor |
| length | 84 s | about a quarter longer (the renderer counts 23%): seven pane changes, about 9.5 s of it |
The caption band is not gained as narrated rows (it is under a paused
player's controls in either form); what is gained is the state column given
to the narration and the program column to fewer, taller panes, and text
that says where it speaks.
## 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 (in a dump, its bytes from the first that changed to the last, 1 f apart; never the whole field) | 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. **On a beat** the caption names, with no step (rsp in the introduction's III2, rax in its IV3): the register framed as read (6 f), the line 6 f after (36 f, `standard`, the name riding its head), held as the beat says, then drawn back toward its head over 18 f with the register's frame, the head fading over the draw-back's last third: never gone in one frame |
| `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 |
| `touch` | the current row and the stack word it reads or writes (`tied`) | right after the fire, before anything the word causes: the line draws from the row's end across the gutter to the word's row, head first, 12 f (18 f when its leg is longer than six rows), `standard`; only when the head has landed is the word armed (a write: 12 f, then struck) or framed (a read, 6 f); only after that does what follows from the word move (a register it fills, rsp's pin climbing onto a pushed word, a span, a role). Held to the advance; drawn back into the row with it, 12 f, or (with `carry` on, for a load) as the carry leaves the word. A store of the value the word already held: the head lands, the arm's frame comes and goes and nothing is struck (in the introduction, where the push is the lesson, it is struck: [motion.md](motion.md#a-word-touched)). A word the window must scroll to: the scroll first, then the touch. At a run and a sprint none: the names stand, and the marks are the run's |
| `carry` | a value's way from its source to its destination (`carry = .arrow`; `.after_touch`: a store's touch first, then its carry) | the source framed `read` first (a register 6 f; a word by its touch); then the arrow draws from it to the destination, head first, 18 f (24 f past eight rows), `standard`; on its landing the destination is armed (12 f) and struck; the arrow draws back as the strike lands (18 f); only then what follows (a link from the register filled, a pin's travel). At a run and a sprint none |
| `aim` | a code address and its row (`aim = .step`, `.standing` or `.drawn`, the author's) | after the word's own strike or read: the line draws from the word to the row, head first, 18 f (24 past ten rows), `standard`, the row's address framed in code's ink as it lands (6 f); held to the advance, or standing at 60% through the beat (`drawn`: drawn so on its beat, at full ink, falling to 60% (18 f) as the next step begins); a word written again: the head glides to the new row (24 f, `glide`), goes to the rule as a stub with the row's name, or frays (dashed 12 f, then out 18 f) when the value is no longer code; at a `ret`, the plaque jumps where it points and the aim draws back as it lands. At a run and a sprint none |
| `follow` | the stack's window, after rsp's pin | only once the pin has landed and never with it: where the headroom over rsp is under two free words, or the newest frame's return address under the window's foot, the rows glide by whole slots, 24 f and 2 f a further slot, 36 f at most, `glide`, the pins riding their rows, the strip's window with them. A climb longer than the room over the pin is one move: the pin travels to the window's top, and the rows take the rest of the distance under it on the same curve. Farther than the window: `unroll`, the pin along the column, `roll` |
| `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. **rsp's and rbp's pins** are the stack's event and are given time: 24 f to the next row and 6 f a further row, 48 f at most, `glide`; the amount on the pin from its first frame, counting as it crosses each row (`rsp -8`, `-10`, `-18`, in write's vermilion, bold; in the introduction `-0x10`, `-0x18`, as its offsets are written: [slot](#slot)), held to the advance and then crossfading to the bare name (12 f); each row it reaches gained (brightening from `free`, 12 f, from the frame the pin's head reaches it, its role fading in with it) or released (to `free`, 12 f); the bracket over the rows crossed drawing with it; the newest span's end riding it; the register struck as the pin lands, and the row's amount with it. rbp's flight to rsp's row: the same, the names meeting in pwndbg's order (rsp slides aside, 12 f, before rbp lands). At a run: 8 f and 2 f a row, 16 f at most, drawn over the veil (the pins, the bracket, the span and the rows' gain or release stand clear of it; the rest of the stack stays veiled), no amount; at a sprint, on the map, rsp is the edge of the stack column's newest frame, moving with each moment (4 f), the spans growing and shrinking with it |
| `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 it opened in. A loupe the narration keeps across steps closes at each advance and opens again in the idea's slot of the next step that concerns it (36 f, as `open`): the steps between are not drawn under it. Open 120 f without a change is the most |
| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and each pane's column of the map becomes its 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; on the same move the rest of each window's column (the map's panel it is a window on) squeezes into its pane's strip: from its place at half size to the strip's rect, its width and its height each on its logarithm (to 36 of 880, and 4 of 24 a row), so the text thins to strokes as it lands, the window's outline riding on it to become the strip's window; the map's parts no pane takes (the backtrace, the key, the memory round pointers, a loupe's panel) fade where they are, 24 to 72. On the same move the registers' window (the panel whole on the map, every chain) [`fold`](#6-verbs)s as it lands, on the move's 72 f, so that the panel arrives at its height in the frame. 72 to 96: the drawing, whose sizes may differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: each squeezed column crossfades into its strip's strokes; the frame's tags, rules and lanes fade in; the veil goes with the last of the map. 96 to 132: still (mock 20) |
| `surface` | from the working frame to the map | the dive backwards, a little quicker: 0 to 12 the tags, rules and lanes fade out and each strip's strokes become its column's text; 12 to 84, `glide`, each pane shrinks into its window on the map as its strip unfolds into the column round it, the map's other parts fading in where they are; 84 to 96 the veil lifts; then the map is still 36 f before anything plays on it |
| `flash` | a pane's minimap, at a mark its window does not show | a ring 8 across in the mark's colour, on the mark's row in the strip, draws out to 14 and is gone, 12 f, with the mark's own strike or read |
| `unroll` | a pane, to its whole column, for a beat, without leaving the frame ("the whole function", "the whole stack") | the strip's column grows out of the strip over the pane and the panes under it (veiled, 18 f), to the stage's height or the column's, a row of the map's 4 units scaling up on the logarithm to as many as fit (sort's 79 rows of text in 840: 10 a row, shapes and inks; a 22-line file at 24, readable), `glide`, 36 f; the window's outline rides from the strip to its place in the column; the pane's own rows are that window, so nothing appears or vanishes: they are the column's rows round the outline. Held while the caption needs it (60 f at least). `roll` is the reverse, 36 f: the column shrinks back into the strip, the outline lands as the strip's window, the panes under it unveil. A far jump in the same column is `unroll`, the window travelling to its new place along the column (24 f, `glide`), and `roll` |
| `descend` | a call the narration follows down | 0 to 12 fire on the call row; then the call's push, as for any call ([stack's own instructions](motion.md#the-stacks-own-instructions)): the touch to the free word over rsp (18 to 30), the return address armed and struck (30 to 42), rsp's pin climbing onto it and rsp struck as it lands (48 to 72), the window following (78 to 102); then the caller's window closes round its call row, in two moves and never both at once: 108 to 120 the rows it gives up fade (those after its return row, and from its top as many as the callee needs), then 120 to 138 the rows it keeps glide up to their places (`glide`), where they move at all; 126 to 138 the call row's plaque becomes the ring; 138 to 156 the call lane draws down from the ring, head first, `standard`; 150 to 162 the callee's head fades in rising 8 as the lane reaches it; 156 to 180 its rows, top down, 2 f apart, 12 f each; 180 to 192 the advance: the plaque lands on the callee's first row, and the source line goes `waiting` (6 f) where the callee has none. Through a stub's `jmp`: the stub's other rows fade (12 f), then its `jmp` row, `pass`, glides to its place (18 f, `glide`), the lane runs on to the next head (18 f), the next window comes in the same way. A label that changes with it (the stack span's name, the source's tag) crossfades, 12 f |
| `cross` | a `syscall` row, in a descent | 0 to 12 fire; 18 to 36 the registers that carry the call framed as read, 6 f apart, the argument rows under the row with them (`echo`); 48 to 72 the crossing lane draws down, 3 units, vellum; 66 to 78 the kernel's window opens as it lands, the vellum filling down from the lane's head; 78 to 90 its head and the call fade in, 6 f apart; the work (bytes given or filled, motion.md's chart); `returns` struck; then the answer climbs the lane (24 f) and rax is struck as it lands, the clobbered registers 6 f apart after it, the log's new row fading in (secondary); hold 36; the advance: the kernel's window draws back up into the lane (12 f) and the lane into the plaque (12 f) as the plaque moves on |
| `ascend` | a `ret` out of a descent's window | 0 to 12 fire; 18 to 30 the touch (read) to the return address, framed 30 to 36; 42 to 66 rsp's pin falls past it, the word released, the callee's span shrinking away, rsp struck as the pin lands (66); 72 to 96 the stack's window follows; then 96 to 120 the descent's window closes, its rows fading bottom up, 2 f apart, 12 f each, its head last; 120 to 132 the lane draws back up into the ring; the caller's window opens in the reverse order of its closing: 132 to 150 the rows it kept glide back down (`glide`), then 150 to 162 the rows it gave up fade in; 162 to 174 the ring becomes a trail bar, the call row's annotation takes the result (6 f), and the plaque lands on the row after the call; the source line from `waiting` to `current` |
| `leave` | a block of a graph, along an edge | 0 to 12 fire on its last row (in the disassembly under the source; in the lens its pill's gold frame pulses with it); a conditional's compare row has its chips framed as read (18 to 24): the cause; 24 to 42 the edge it takes draws gold (3 units) from the source pill's frame to the target's, head first, `standard`; then the mark travels it: the gold plaque (22, its point the way it goes) leaves the pill along the edge, round an arc of the ring or along a way out, `glide`, 12 f and 2 f a 100 units, 12 f at least and 42 f at most (sort's steps round a ring, 58 to 72 units, 12 f; its inner loop's way out, 318, 18 f), the pill cooling to the trail as it goes; it lands on the target (the advance) and 6 f after, the target's count is armed and struck; with the landing the oldest of the three trail edges cools to `dim` (18 f). The first time an edge or a block is reached it is also a `reach`. At a walk, 1.5 s |
| `turn` | a loop's back edge | `leave` round the ring's foot from the latch up into the header at 9 o'clock: an arc, the mark at its speed (sort's inner, 58 units, and outer, 50, 12 f each); the count at the ring's centre is armed as the mark leaves the latch and struck as it lands. The mark going round the ring, step by step and then this, is the picture of iteration; at a run the whole loop goes round in one sweep of 8 f a step |
| `reach` | a block or an edge of a graph the run reaches for the first time | the edge draws gold under the mark, from `rule` (the `leave`'s own draw); as the mark lands, the pill fills from the page to `raised` (12 f), its offset brightening from faint to primary, and `×1` fades in (6 f) and is struck. Its counts begin here, never before |
| `unfold` | a fold of blocks not reached yet, when the run reaches one of them | as the mark sets off along the edge into the fold: the pills beyond the fold make room along the layout's own way (round the ring, or down the layers), 24 f, `glide`; the dashed pill splits into its blocks' quiet pills in their places (12 f, 2 f apart in address order); then the mark lands on the one reached (`reach`). A fold only opens |
| `regroup` | bytes into a word (the introduction) | walked, on the dump's first word, the return address at a function's first instruction ([chart](motion.md#a-word-read), mock 37): the dump goes from sixteen bytes a row to eight (each right half down a row, then left); the other rows are veiled and the dump's header goes; the word's offsets fade in over its bytes, in the header's row, `low byte` left of the first and `high byte` right of the last, outside the run; then the bytes themselves fly, the low byte first, one at a time (24 f each, 18 f apart: the next lifts as one comes down, so none crosses another): straight up to 40 over the row, clear of the offsets, over, and straight down onto their pair's place in the word's field, 30 apart and ranged right, so that they land reversed; each bright and bold in the air on its own ground, its offset riding over it and landing over it; a label goes as its byte lifts (`high byte` as the byte that lands under it lifts) and comes back on the far side as it lands; a faint copy fades into each one's place in the dump once it has left: no row of memory is crossed or printed over; the gaps close to sixteen digits (12 f), the offsets and labels going with them; the zeros in front are bracketed, `zeros in front` on a ground only as wide as its label, and fade (12 f). At a run (the other fifteen): each row's word fades in (8 f) as its bytes dim, rows 6 f apart, each written as the stack will write it (an address bare, a number as [`value`](#value) writes it). The word field is eight pairs wide, so a word is always ranged right, its low byte last |
| `ink` | a word becoming an address | its digits go from primary to its region's ink (12 f), and the band it points into in `segments` is framed as read inside its box, with the band's row of names (6 f): an echo, no line. The first walked, held 60 f; the rest at a run, 2 f apart, each band framed 12 f |
| `enlarge` | a box of `segments`, out of its line on the whole | 0 to 6 the cluster's line on the whole framed bright; 6 to 78, `glide`, the box rides out along the magnification: its left corners travel the two lines from the line to their places, the lines drawn behind them, the box as tall as they are apart and as wide as the ride is far (the bar's 20 to its 180), its bands drawn at its scale all the way (a mapping a 2-unit line until it is taller; the gaps opening); 78 to 90 its page lines fade in and the frame on the line goes; then its names, rows top down, 2 f apart: an edge's leader draws from the box (6 f), then its address fades in (12 f); a band's row fades in (12 f). The clusters in address order, each riding out as the one before lands ([chart](motion.md#the-address-space-enlarged)) |
| `column` | rows gaining a column (offsets, roles, pins, lines) | the rows make room (18 f, as rows do), then the column's values fade in top down, 2 f apart, 12 f each |
| `frame up` | a panel arriving round rows already built | its rule draws round them (12 f), then its tag fades in (12 f): the last thing, never the first |
| `decode` | an instruction's bytes becoming its row | the bytes of one instruction gather (12 f), the mnemonic and operands fade in beside them (12 f), and the bytes dim; the row then travels to its place (`glide`, 24 f) |
| `align` | the stacked program column to `aligned`, and back (`stack`); one form of `aligned` to the other | the band and the state column fade out (12 f); the panel widens to both columns (24 f, `glide`); the source's lines glide to their heads and the instructions glide in under them (36 f, rows making room), each instruction from its row in the disassembly to its row under its line; the heads' paper and rules fade in last (12 f). `stack` is the reverse. `interleaved` to `columns`: the addresses and instructions glide right into the instruction column (24 f, `glide`), then every row glides to its height in the new form, each line level with its run's first row (24 f, `glide`); the rules move with their groups; the lines with no code fade into the room made for them (12 f). Back, the same in reverse, the no-code lines first |
| `unpack` | a register's row, into its [`parts`](#reg) | the rows under it make room (18 f, `glide`); its value spreads into its eight bytes, the pairs opening apart and the zeros in front coming in at `pad` (12 f, `glide`); the parts' rows come in widest first, each its bracket and its name (12 f, 6 f apart). Walked around a step that names a part ([chart](motion.md#a-registers-parts)); never at a run |
| `pack` | a register's parts, back into its row | after the step's cool: the parts' rows fade (12 f); then one move, the bytes closing into the value as [`value`](#value) writes it while the rows under it close up (24 f, `glide`) |
| `fold` | a registers panel, its quiet registers | each quiet register's row glides into its cell, three to a row on a pitch of 285, in pwndbg's order, its chain past the first hop fading over the first 24 f; the rows under them (rip's) glide up with them; then the rule over the first folded row draws (12 f): 36 f, `glide`, on a beat of its own (the introduction's II8). In a `dive` the same, on the dive's move; backwards only in a `surface`, on its way to the map |
| `title` | a chapter, at its seam | from e, the frame the chapter before has its last text read: still 30 f; its texts leave together (12 f); the title arrives in the caption's place (18 f, rising 8), the clock's label crossfading 6 f after; still 60 f; the chapter's opening under it; the title leaves at its reading time or the opening's end, the later; the first text 6 f after. A pause of 2.1 s, e to e+126 ([chart](motion.md#captions-opening-closing)). The scene's first chapter: the title at 6 f, its first step still by 240 |
| `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`; under `tied` the touch first), 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. A read is a cause, not an effect, and goes before what it fills: a load's word is reached and framed in the first slot (18), the register it fills struck in the next (36). Under `tied` the order is the instruction's own, cause to effect, and nothing downstream is armed or marked while what is upstream of it has not shown: the row fires; the touch leaves it; the word reacts on its landing; then what follows from the word (a register filled, rsp's pin onto a pushed word, the span, a role); then the window follows. A step that moves rsp or rbp and touches no word (`sub rsp`, `mov rbp, rsp`) has the pin's travel as its effect, the register struck as the pin lands |
| `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. **A call stepped over** is a continue over one call, its result first: rax armed and struck as a walked register's, the call's annotation taking its C form and result with it, then the others in the wave ([chart](motion.md#a-call-stepped-over)) |
| `run` | steps that need not be read | over a graph, the mark goes from block to block in 8 f, round the rings, each edge taken flashes to gold and cools in 8 f, counts change in place; at a sprint (on the map) the gold moves only when the block changes, 4 f at most each, the trail's three edges following and the loops' counts ticking at their centres, and the picture settles at the phrase's end. Elsewhere: 18 f a step; no fire, arm or pulse; the mark, cards, nodes and pins ease in 8 f; no strikes, no held corners and no arcs drawing: a value changes in place under an 8 f crossfade, unmarked, and what the run changed is shown settled when it ends (its arcs fade in, 8 f, standing; no corners); no ties but the thread. A caption never names what a run veils. 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 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 on the pane's minimap glides with it, the same 24 f (a window fading through moves on its minimap with the fade's out, so the strip shows where it went first). 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 (eight lines, eleven instructions, twelve slots as the subject) does not scroll, which would only blur: at a walk the pane `unroll`s, its window travels along the column, and it `roll`s back in at the new place; at a run it fades out (12 f) and in at its new place (12 f); either way 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) |
**Nothing changes in one frame.** A label that changes in place (a tag's
note, a span's name, a box's name, the source's tag) crossfades over 12
f; a count that appears fades in (6 f) and is then armed and struck; a
value written is struck; a window going far fades through. The
instruments' POP finds any one-frame change after stillness.
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.7 s for a call and 3.6 s
for a return across three levels, 2.7 s for a swap; 3.6 s to follow a
call down (its push walked in cause order), 3.6 s for a crossing (4.9 s when
it moves bytes), 3.3 s back up.
## Composition
**What may contain what.**
- The working frame holds the band and two columns; the band is two
panels, one over each column, or its drawing alone over the program column (a lens with no view). 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, or (a descent) a tag and windows of
rows under their heads. A row holds atoms. Nothing nests deeper.
- Every panel shows the same moment. A register from one stop beside a
stack from another is a lie, however small.
- A mark sits on an atom or a row, never on a panel. A panel's only
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 fact from after the moment shown.** Every block draws what the
recording holds up to the moment on screen and nothing later: a count
so far, never the total; a layout from the code or from what has
happened, never from what will (a graph's blocks placed by how often
the run will reach them); no mark for "never" that the rest of the run
decides (an edge never taken, a block never reached); no fold of what
will not be reached. What is not known yet is quiet until it is, and
its arrival is a verb (`reach`, `unfold`). A scene's caption may say
what comes; the picture may not.
- A text scrolled farther than its window's height: it unrolls to its column and rolls back in at the new place, or at a run 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, 16 and 17, one function a block under
the block's name; `mock/map.py` draws the working frame from a fresh
recording of `targets/list` (9 to 11, 21), the map (19) and the dive (20);
`mock/dense.py` holds that recording's data and draws the marks sheet
(15); `mock/graph.py` draws the graphs (22, 24 and the forms sheet 43)
from `sort-clang.dis` (sort as the scene builds it, clang -O0),
`reverse-O0.dis` and `libc-open.dis` and the paths their runs took;
`mock/frame.py` draws the reworked frame (40, 41 from the list recording;
25 from sort's stop in `sort-dbg.txt`) and the layouts sheet (42);
`mock/heap.py` draws the heap scene's storyboard (18) from a
recording of `mock/heap.c`; `mock/intro.py` draws the introduction and
its blocks (29 to 37) from the same list recording and its mappings;
`mock/gen.py` draws 1 to 8; `mock/touch.py` draws the disassembly tied to the
stack (44 to 48) and the carry (56) from a fresh recording of `reverse` and its call; `mock/column.py`
the column (49 to 55) from a fresh recording of `hello`; `mock/regs.py` the introduction's chapter on
registers (58 to 61) and its seam from chapter I (62) from a fresh recording of the introduction's program
from line 40. Each working
frame has a `-480.png` beside it; the map has its 1080p (`19-map-1080.png`).
```sh
cd design/mock
python3 -B context.py && for n in 12-calls-subject 13-sqlite-row 14-sqlite-page; do
resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done; resvg 16-descent.svg 16-descent.png
resvg 17-operands.svg 17-operands.png
python3 -B heap.py && for n in 18-heap 18-heap-free; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done
python3 -B graph.py && for n in 22-graph-sort 24-graph-strip 43-graph-forms; do resvg $n.svg $n.png; done
python3 -B frame.py && for n in 40-frame-beside 41-frame-subject 25-blocks-lens; do # 42 it composes itself
resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done
python3 -B pair.py && for n in 26-pair-rest 27-pair-store 28-pair-part 38-pair-ret; do resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done
python3 -B intro.py && for n in 29-intro-bytes 30-intro-words 31-intro-stack 32-intro-code 33-aligned 34-segments \
35-segments-abc 36-aligned-columns 37-regroup; do resvg $n.svg $n.png; done
for n in 30-intro-words 34-segments 36-aligned-columns; do 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
resvg -w 1920 19-map.svg 19-map-1080.png
python3 -B gen.py # 1 to 8, then resvg the same way
python3 -B touch.py # 44 to 48, 56 and 57 (it runs resvg and composes its sheets itself)
python3 -B column.py # 49 to 55 (the same)
python3 -B regs.py # 58 to 62 (the same)
```
| Mock | Is | Blocks it shows |
| --- | --- | --- |
| [40](mock/40-frame-beside.png) | 9 in the reworked frame: `beside`, at rest | the registers `quiet`: rax rcx rdi rbp rsp as rows with their chains, the eleven others three to a row under a rule, rip last; fifteen stack slots and the three frames they belong to; the source's eight lines over seventeen instructions; each pane's minimap |
| [41](mock/41-frame-subject.png) | 11 in the reworked frame: `subject`, mid-step | the band as before (296, a view of seven); eight lines over eleven instructions; ten rows of registers, rdi struck and its link climbing the gutter from its new row; thirteen stack slots |
| [42](mock/42-frame-layouts.png) | the frame three ways, at a third of their size: A (recommended), B, C, each as 41's moment and as 25's | A folds the quiet registers; B keeps all seventeen and gives the source's rows to the disassembly (the stack stays six); C sets the registers in two columns (chains cut to a hop); under each tile its rows |
| [44](mock/44-tied-store.png) | `next = cur->next` stored (`mov [rbp - 0x18], rax`, the loop's second turn), mid-step, in layout A as `subject`: `whole` over `tied` | `whole`: each row's chain from its address, the store's own cut to `7fffffffecc8 → …` beside the minimap, so its strike is off the row; offsets from rsp. `tied`: `cur → 405030`, `405038 → 405010` (the heap word the view holds), `next → 405010` struck with the stack's word; offsets from rbp, `-18` the operand's `0x18`; the `touch` from the row up the gutter's middle lane to `next`'s word |
| [45](mock/45-tied-load.png) | the next step, `mov rcx, [rbp - 8]`: `prev` read into rcx | `prev` framed `read` with its word (echo) and the touch in read's colour; rcx struck and its link climbing to its pin under 9's node (the touch, the link and the thread: the three lines) |
| [46](mock/46-tied-call.png) | `call reverse`, five instants of the step, numbered in their order | 1 the fire alone, the row saying `reverse() · rsp -8`, two free words over rsp; 2 the touch to the free word rsp − 8, nothing else moved; 3 the word armed and struck, `main+50`, rsp not moved; 4 rsp's pin climbing onto it (its path a few frames apart), `-8` on it, the bracket, reverse's span arriving, rsp struck as it lands; 5 the window following by a row |
| [47](mock/47-tied-prologue.png) | reverse's prologue, six instants numbered in their order | `push rbp`: 1 the touch to the free word, 2 the word written (rbp's own value: the arm's frame, no strike), 3 rsp's pin onto it, `saved rbp` arriving; `mov rbp, rsp`: 4 rbp's pin flown from main's saved rbp to rsp's row, the two meeting, the base to rbp; `sub rsp, 0x18`: 5 the climb at its first row, `-8`, 6 landed at `-18`, three words gained, the rows slid under the pin for the last of it |
| [48](mock/48-tied-ways.png) | the sheet: three ways to say the row and its word are one thing, on 44's instant | A, names and the echo alone, pwndbg's offsets; B (recommended, `tied`), names, offsets from the frame's base and the touch; C, the name in the operand as IDA writes it, the row saying only what moved |
| [56](mock/56-carry.png) | `carry = .arrow` with `tied`, six instants numbered in their order: the load `mov rcx, [rbp - 8]`, then the store `mov [rbp - 0x18], rax` | the load: 1 the touch and `prev` read, rcx untouched; 2 the touch withdrawn as the carry climbs the gutter's right lane to rcx, its open chevron landing, rcx armed; 3 rcx struck, the carry gone, rcx's link to its pin. The store: 4 rax framed read, memory unmoved; 5 the carry down to `next`'s word, armed on its landing; 6 struck |
| [57](mock/57-aim.png) | `aim = .step` on `call reverse`, the instant after the return address is struck (46's third instant) | the touch drawn back as the aim leaves the word: from the return address up the gutter's left lane onto the disassembly's right rule at `401272`, the row after the call, its address framed in code's ink; rsp's pin not yet moved |
| [58](mock/58-regs-pins.png) | the introduction's II3, held: rsp and rbp point into the stack | the `registers` built, every register a row, chrome and legend last; `segments` live: rip's row pin on list's code row (`◂ rip`, II2's, standing), rbp's and rsp's `under` pin in the stack's band, the band and its row framed with their values (`ink`'s echo); the 128 bytes on the shelf over the address space; the clock and its label, `II registers` |
| [59](mock/59-regs-parts.png) | II5, struck: `mov edi, 0x10` | `reg`'s `parts`: rdi's eight bytes, the zeros in front at `pad`, `edi` `di` `dil` bracketed under the low ones; the operand `edi`, the part and its four bytes framed together; the one byte that changed struck, and the row's annotation with it; push's rows with no panel yet, the pc's; two texts beside on the left, the older dimmed |
| [60](mock/60-regs-call.png) | II6, mid-step: `call malloc@plt` stepped over | rax struck with the result and the call's annotation with it, `malloc(16) = 405050`; rcx, rsi, rdi struck in the wave; r11's later hop held; PF and ZF set, held; the mark not yet moved; three texts beside |
| [61](mock/61-regs-fold.png) | II8, the chapter's last picture | `fold` done: six rows, ten registers three to a row under a rule, rip; the corners of II6 and II7; the 128 bytes back from the shelf at the rows III's stack gives them, with I's three chains; reverse's rows, the pc on `push rbp`; the clock at 182 of 193 |
| [62](mock/62-seam.png) | the seam from I to II, four instants at half size | `title`: I's last picture read; the title said, the label changed; the 128 bytes folding to the shelf along its height; II1's text landed and the registers' first rows arriving |
| [49](mock/49-column-call.png) | the column: `open`'s call (`hello`, moments 37 to 38), mid-step | the `shelf` (the log, its bytes, the registers with rsp struck on their tag); source 3, main's window, a stack of nineteen words; the touch down the gutter onto the stack's right rule; the newest bubble on its paper, level with the call row, the older one dimmed above it |
| [50](mock/50-column-stub.png) | the stub's `jmp` (38), the rest before its step | the descent in the column with the stack kept under it, the return address held on its top; the bubble's stem across the gutter to the jmp row |
| [51](mock/51-column-args.png) | libc's `open`, its last three walked (61 to 64), mid-step of `mov eax, 0x101` | the registers unfolded under the descent, rip's row above 888; the bubble level with the first of the three |
| [52](mock/52-column-cross.png) | the crossing (64 to 65), mid-step | the descent 24 rows, the kernel's window at its floor; rax 3 struck on the registers' tag; the newest bubble at the kernel's height, the lowest |
| [53](mock/53-column-back.png) | back up and stored (74 to 76) | main's window whole, the call ran with its result; `f ◂ 3` struck and its touch; the newest bubble climbed back to the call row, the crossing's below it |
| [54](mock/54-column-present.png) | the crossing in the present frame (`beside`) over the column | what each shows of one instant: 17 rows of descent against 24, the state panes against their tags, the caption against the bubbles |
| [55](mock/55-column-graph.png) | a wide subject: sort's rings (25's stop) across the stage, twice their size, the program and state on the shelf | a bubble `on` the drawing, in the free corner over the outer ring, its stem round the drawing's top onto `+56` |
| [9](mock/09-context.png) | `beside`, at rest, in the frame before this round's rework (40 is it reworked): `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; each pane's minimap (source, disassembly, stack, the view), its window, the current row; the registers and the drawing without |
| [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 minimaps: the pc gold and the read cyan on the disassembly's, the read row on the view's; the annotation at 540, whole |
| [11](mock/11-context-lens.png) | `subject`, mid-step, in the frame before the rework (41 is it reworked) | the band at 296 and 200, the drawing a size up, a dump of seven, nine instructions, six slots; the minimaps at the subject's window sizes, the disassembly's and the stack's scrolled round their 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, newest at the bottom beside the tree; `call` spans with arguments; the stack's row with offsets and a role; a `projection` from the return address to the new node; operands of 27 characters whole |
| [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing, `#0` at the bottom over its source line; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in |
| [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the calls so far in the band, strace's way, the newest whole and held; the call through a pointer by its target's name, `→ __pwrite64`; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed |
| [15](mock/15-marks.png) | the marks sheet: `current`, `struck`, `held` as A (the first videos), B (the catalogue's) and C (a whiter reading), on rows of the list at the load and the store after it | the source's current line; the pc's row; rip; a struck and two held registers; a dump row struck on the one byte that changed and one held; a lens's cell held and struck; the same rows at 1.35 times |
| [19](mock/19-map.png) | the map, mid-step with a loupe open: the same moment unfolded on 3840 by 2160 ([at 1080p](mock/19-map-1080.png)) | the file whole; 69 instructions; memory, the registers, the backtrace whole; the stack from 16 words above rsp, continued at the third column's foot and folded into `more` at the process's start; the loupe as a panel beside memory; `arc`s in memory, the loupe and the stack (the frame chain left to the spans); the key; the thread across the gutter; the working frame's windows outlined |
| [20](mock/20-dive.png) | `dive`, four instants on one sheet, each at the working frame's size | frame 0 the map; 24 the windows bright, the rest veiled; 60 halfway, the panels rising out of the map, each column squeezing toward its pane's strip, the rest fading where it is; 96 the working frame, each pane 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); no minimap for the loupe: the panes' strips stand as in 10 |
| [39](mock/39-minimap-1to1.png) | three panes' minimaps cut from 10 at 1:1, a pixel of 1080p a unit | what a strip lets a viewer read at 1080p: the column's shape and inks, the window, the pc gold, a read cyan; the stack's 48 of 103 rows round its window |
| [16](mock/16-descent.png) | the syscalls scene's `open` followed down, four instants of the program column (`ztrace dbg` on `anim/tools/hello.c`, moments 1 to 6) | `descent`: main's window, its spare rows above its call and one row after it, the PLT stub's head directly under that row (its neighbour `_start` `outside`), libc's `open`, the kernel's window on vellum; `insn` `waiting` and `pass`; the call lane and the crossing lane; `line` `waiting` and the waiting thread; a PLT target named, an indirect jump's target, a `lea`'s result, a named place (the canary), a system call's number and its arguments hanging under it; libc's twelve-digit addresses moving their own window's columns; the descent closed again, the call `ran` with its result |
| [17](mock/17-operands.png) | operands before and after, on real rows of list, hello and libc's `open`; then the row's detail | size words gone; `width` on an immediate store, a byte compare, a sign-extending load; padding faint; a compare's two values and the flags it leaves; conditionals reading them; `lea`'s sum; an indirect jump through `open@got` |
| [18](mock/18-heap.png) | the heap scene, five instants of the band: `ztrace dbg` on `mock/heap.c`, glibc 2.44, after each malloc and free (2 a run's end, settled, unmarked) | `nodes` in two rows, a `bin` heading the second (`dummy tcache` before the first free); a free chunk drawn `freed`, its link in its first word; `bytes` read as `size` (`0x20 a m P`) and `protected` (`→ 405050 ^ 405`), notes (`key`, `the old link`); the free list and the program's list as `arc`s; struck bytes, one byte of a pointer struck alone |
| [18, the free](mock/18-heap-free.png) | beat 3 in the working frame, mid-step | the register wave a stepped-over call leaves; a `loupe` from the band's view lying over the stack, never the registers, its stem down the gutter's right lane; `rdi` still on the freed chunk; the tcache's two fields, `0x2f8 bytes` |
| [22](mock/22-graph-sort.png) | the map's first two columns at sort's 11th compare (clang -O0, `sort-dbg.txt`) | the `blocks` lens's rings at their size over the source whole; the disassembly linear, 69 rows (swap, sort, main), each block's first row ruled with its visits so far, `+a7` (not reached yet) with none; the thread across the gutter; the frame's windows outlined on the rows' edges |
| [24](mock/24-graph-strip.png) | reverse's loop as a ring, four instants | `leave`: the condition, the edge lit gold and the mark on the ring's top; `turn`: the mark round the ring's foot, the count at its centre struck (`2 turns`); the way out down the header's tangent to `+48`, reached the first time (`×1`) |
| [25](mock/25-blocks-lens.png) | sort at the 11th compare in the reworked frame with the `blocks` lens | `rings` over the program column, 880 by 344, whole: two rings, the inner touching the outer at its header, upright pills with offsets, calls (`swap`) and visits so far, the pc's gold, the fork inside the inner ring not taken yet, the ways out down the tangents (the function's not taken yet, `+a7` quiet), the turns at the centres, the trail; no view: the disassembly under the source, eleven rows, each block's rule and visits, the thread to line 12's run; registers `quiet` from the state column's top; twenty stack slots in sort's, main's and libc's frames; each pane's minimap |
| [43](mock/43-graph-forms.png) | the graph's two forms at the lens's scale, every count as of the moment shown | `rings` on sort, whole in 880 by 344; `layers` (pills, round corners) on sort, past the pane, veiled; `layers` on libc's `open` at its `syscall`, a tree of branches, its blocks not reached yet folded into two dashed pills (`+5b … · 7`, `+be … · 8`) and `+d0` quiet; why each, and why the track is withdrawn |
| [26](mock/26-pair-rest.png) | the `pair` at the loop, i = 15: plain and ASan builds of `overflow.c` | the shared source with each run's mark on its side; two disassemblies aligned by line, ASan's `only here` rows; the line's registers; each frame as bytes (`hexdump` `eight`): plain's `i`, `buf` (`41`s and their `"AAAAAAA"`), the saved rbp and the return address under the span; ASan's fake frame, its header's fields and shadow beside each row, the real stack's way back under a rule; `buf` facing `buf`, the saved rbp facing the redzone (`differs`) |
| [27](mock/27-pair-store.png) | one turn of the loop, row by row: plain's eight instructions each facing its counterpart among ASan's seventeen | `only here` bars; the page facing the check; the check's values (`0 : 0 ZF`, `taken`); the partial check and the report's call faint, off the path at 00; under each, its `buf` as bytes, the turn's one byte struck and the reading a letter longer, ASan's shadow framed as read |
| [28](mock/28-pair-part.png) | i = 16, the step in which they part | plain's store struck on the saved rbp's first byte, `41` among its stack-ink bytes, its reading `→ 7fffffffed41`; ASan's shadow load framed reading `f3`, its compare and the branch not taken, its redzone still `00`; `differs` on the facing rows |
| [38](mock/38-pair-ret.png) | i = 27, plain alone: the return address half overwritten; the ASan scene's poster | the saved rbp all letters, reading `0x4141414141414141`; the return address `41 41 41 41 00 00 00 00`, held on three bytes and struck on the fourth, reading `0x41414141`, no arrow, no name; ASan stopped: its disassembly down to `call __asan_report_store1`, `never returned`; its stderr panel, the report's lines cut at the edge, four framed; its frame's last picture |
| [29](mock/29-intro-bytes.png) | the introduction's first picture, the camera at x2: 128 bytes, nothing else | a raw hexdump, before any ink, its header naming only what is shown (`128 bytes at 7fffffffece0`) |
| [30](mock/30-intro-words.png) | the `ink` beat: the words, eight bytes a row, where the stack will be; the address space in the program column | `regroup` landed, each word ranged right; `segments` at 108 wide, no pins; a dump's place, the `link` standing; `ink`'s echo: the return address and list's code band, with its row |
| [31](mock/31-intro-stack.png) | the same words as the stack panel, the registers built over it, at x1.25 | the stack's conventions: rsp and rbp pins, offsets (the introduction's, `0x` from 0x10 up), roles (`the way back` on a return address), spans |
| [32](mock/32-intro-code.png) | the code chapter: `aligned` with each instruction's bytes between its address and mnemonic | an instruction as bytes, decoded, level with its line |
| [33](mock/33-aligned.png) | the `aligned` split, `interleaved`: reverse and its neighbours, the pc at the load | a line with two runs (20), lines with no code, rows of no line, the band as the thread |
| [34](mock/34-segments.png) | `segments` as a frame, treatment A: the list recording's mappings (`ztrace show`) | the whole with its ends and size; three boxes; the program by segment under its bracket, every other file once; addresses at the edges, sizes, permissions in a row or inside a band; leaders pooled; rsp and rip |
| [35](mock/35-segments-abc.png) | the three treatments as frames, saying less and less | A as 34; B every file once; C the whole alone |
| [36](mock/36-aligned-columns.png) | the `aligned` split, `columns`, on 33's data and `_init` after it | the seam after the longest line; places at each column's start; line 20's cell eight rows tall; its second run; lines 23 to 25 with no code; rows of no line; the pc's wash across both columns |
| [37](mock/37-regroup.png) | `regroup` walked on the return address, `b0 18 00 01 00 00 00 00`: eight instants with their frames | the reflow to eight a row; the offsets over the row, the low and high byte beside them; the flight one at a time over the offsets, the landed offsets over their pairs; landed reversed; the gaps closed; the zeros gone; the run, the numbers as `value` writes them; the ink |
| [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` (the kernel's side is now the descent's floor, 16) |
| [4](mock/04-malloc-glibc-musl.png) | first pass | the allocator drawn to scale; `freed` (now a scene, not a lens: 18) |
| [5](mock/05-memory-write.png) | first pass | a byte grid: the old form of `hexdump`; `struck` and `held` in cells |
| [6](mock/06-title-legend.png) | | `card`, the legend |
| [7](mock/07-sort-swap.png) | first pass | `array`; `travel` |
| [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 jump out of the window, a `rep`, a
`lea` with registers in its sum; the flags' echo; operands giving way
(none in 9 to 17 needs to).
- The descent's motion, its fold of a deep chain, a lazy PLT's resolver
row, the vDSO, a descent into a function of the program's own, and the
descent on the map. The registers and stack beside 16's instants (the
strip is the program column only).
- `value` classes other than digit, small number and string.
- `armed`, `fault`, `attention` and the veil in the context.
- A `projection` from the dump for a write. A `link` to a `slot`, and its
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`, `pages` in the band.
- The heap scene's map and minimap (their places
are in [the scene](motion.md#a-scene-libcs-heap-from-the-inside)), a
node travelling between the rows, a bin of the unsorted or large kind.
- A loupe opened from the stack or the disassembly (18's opens from the
band's view); two in the working frame; a third closing the first.
- The minimaps of 12 to 18: their recordings hold a stack of 64 words or
less and no bytes round targets, so their maps would be mostly gaps.
- `surface`, `flash`, a window gliding on its minimap, a far jump seen on a
strip before the pane fades through; an `arc`'s end on a strip; a
`descent`'s and `aligned`'s strips.
- `enlarge` and a dump's place in motion (charts only); treatments B and C
of `segments` at their own sizes (the sheet has them as frames); `align`
between `interleaved` and `columns`; `columns` with a pc in a long run,
away from its line's row.
- A local's name as a slot's role in the working frame's -O2 recording (none at those pcs; 44 to 53 have them).
- Under `tied`: `pop`, `ret`, `leave`, `enter` and `add rsp` (motion.md's charts only); a touch to a word the
window scrolls to first; the leaf's window over its red zone; a touch giving way to its echo in a step that
draws a link and a projection; `= &buf`; the offsets' base going back to rsp at `pop rbp`; the pins' travel at
a run over the veil and at a sprint on the map; a climb longer than the window (`unroll`); the follow's
one move under a climbing pin (47's sixth instant shows where it ends, not the move); a carry to a folded
register or off a window (a stub); `carry = .value`.
- The introduction's chapter II from its first beat to its last: II1's rows arriving, II2's `◂ rip` coming
in, II4's echo, II7's continue; `unpack` and `pack` and `fold` in motion (charts only); `parts` on rax
(`eax` `ax` `al`) and a write that zeroes a part's high bytes; the seams before III and IV and the video's
first title; the label alone in chapter I.
- The column: a fold and an unfold between beats (charts only); a beat `above`; a loop's bubbles stacking;
the scene's opening `below` and its relayout into the column; the column at a run; the floor holding a
window's continuation under a narrated pane (49 and 53 have the stack's there).
- `pin` with a count; `rwx`.
- Every verb: the mocks are stills. `establish`, `link` and `project`
have no chart from a render yet.
- The reworked frame in the mocks drawn before it: 10, 21 (a loupe from
rdi lies over the folded registers now, and the stack under them is
longer), 12 to 18 and 13's backtrace lens; the map (19) with the
reworked windows outlined, and the dive (20) with the registers folding
as they land. The `none` split reworked. A `quiet` cell read; a scene
that folds none.
- The graph: `reach` and `unfold` (stills of the folds only, in 43);
`layers` panning; three rings deep; a loop with two ways out, or with
its test at its foot (gcc's rotated loops: the header is still the
ring's 9 o'clock, the latch the block before it round the ring); an
indirect jump and a tail jump; a descent's drawings on the map; `leave`
and `turn` from a render; `unroll` and `roll`.
**The data in 22, 24, 25 and 40 to 43** is the recordings' too: sort as
`anim/build.zig` builds it for the scene (clang -O0 -g -no-pie
-fno-stack-protector, less the instrumentation's calls, which add no
block), `objdump -dl` of it (`sort-clang.dis`), its path through the
blocks from `ztrace record --by insn --from sort` (the leaders it hit,
98 of them), and its stop at the 11th compare from `ztrace dbg` under
`env -i setarch -R` (`sort-dbg.txt`: the registers, the instructions, the
array, the stack from 16 words above rsp to its top). The render's
offsets differ (its build has the instrumentation's calls); its blocks
and edges are these. 40 and 41 are 9 and 11's recording.
**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`; 16: `ztrace dbg` on `anim/tools/hello.c`, built
`-O0 -no-pie -Wl,-z,now` and run under `env -i setarch -R`, its libc rows
from that run's disassembly; 17: the same runs and `objdump -d` of
`/usr/lib/libc.so.6`; 18: `ztrace dbg` on `mock/heap.c`, `x 0x405000 1024`
after each malloc and free). The frames' extents are read off the frame-pointer chain.
The older calls in 14's log show `(…)` for their arguments: this mock's
data has only their names and results.
The dump's node bytes are what the chains and the program say the heap
holds; its allocator rows are glibc's layout, with the word nothing reads
drawn as never read. A recording made under ptrace has seen neither. The
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
at 23:07 (7 and 12 on 11 November at 14:15). Since the last round `theme.zig` has the map and the minimap
(`map.zig`), the loupe (`loupe.zig`), the `arc` and the dump's and the
slot's new columns; whether `dive`, `surface` and `flash` are whole there
is not checked here. The tokens are under [Token changes](#token-changes).
1. **Direction** ([direction and nearness](#direction-and-nearness)):
the backtrace with the newest at the bottom (`calls.zig` and
`context.zig` still write `newest on top`), the oldest dropped from the
top, `· 2 more above`; the `syscalls` lens's drawing as the log of
calls ([`syscalls`](#syscalls)), the kernel's side leaving the band
for the descent's floor.
2. **The descent** ([`descent`](#descent)): the disassembly as windows a
call deep, each with its head row and its own address width; `insn`
`waiting` and `pass`; the call lane and the crossing lane; the kernel's
window on vellum; folding past three windows; on the map the column
whole. Its verbs `descend`, `cross`, `ascend`. With it, `line`
`waiting` and the waiting thread (primary, 2), and the source's tag
saying where the pc is.
3. **Operands** ([`insn`](#insn), [`width`](#width)): every size word
dropped; a `width` of byte cells where no register of the instruction
has the access's size and the mnemonic does not fix it; `nop` and
`endbr64` faint.
4. **The row's detail** ([`insn`](#insn)'s annotations): a compare's two
values and the flags it leaves, as chips; a conditional's `· reads`,
and its echo on the setting row and rip's flags while it is current;
`lea`'s `=`; an indirect call's or jump's target and the slot it was
read from, the target's name the last thing to go; a PLT stub named in
the operand (`401070 open@plt`) and the function it reaches in the
annotation; places the C library's layout names (`fs:[0x28]`, the
canary); a `rep`'s count; a system call's name and number, its
arguments hanging under it; a ran call in C's form with its result.
5. **Malloc's words** ([`bytes`](#bytes)): field reads `size` (the size,
`A M P` as chips) and `protected` (the pointer protected, the mask,
the arc to the pointer), and a field's note.
6. **`nodes` in two rows** ([`nodes`](#nodes)): the program's list over a
free list, a node travelling between them, the free form (dashed,
hatched `key`, its link from the first word), and the `bin` box
heading the second row.
7. **The graph** ([`graph`](#graph)). What `graph.zig` draws (as read on
11 November at 14:15: the layered form, laid out by the whole
recording's counts, folding the runs of blocks the whole recording
never reaches, drawing the edges never taken) must change in four
ways. **Nothing from after the moment**: the layout a function of the
code alone (back edges by the walk from the entry in address order,
layers by the longest path, a block under its fall-through
predecessor), never of `countBy`'s `whole` counts; no fold by
`reached` over the whole recording and no never-taken ink: a block or
an edge is quiet until the moment it is first reached (`reach`), and a
fold is of blocks not reached by the moment shown, opening as the run
gets there (`unfold`), its room kept so that only what lies beyond it
moves. **`rings`**, the first form: the natural loops (merged by
header), each a circle of its blocks at their centres clockwise from
the header at 9 o'clock, radius as its upright pills need 12 apart; a
nested loop's ring outside its parent at the parent's 3 o'clock; arcs
for steps round the ring and the back edge; an arc 30 inside for a fork
within a loop; a way out down its block's tangent and quarter circles
of 16; outside the loops, `layers`; the turns at the ring's centre, 30
under it. **`layers`**, the second, as it is but pills for boxes and
quarter circles of 12 for its corners. **Both**: a block a pill with
its offset, the functions it calls (faint), its visits so far; `leave`
and `turn` along arcs (2 f a 100 units, 12 f at least); the map draws
the drawing as any lens's, and its disassembly column stays linear
with each block's rule and visits (the two-column graph with rows on
the map, and `spread` and `gather`, go).
8. **The pair** ([`pair`](#pair)): the split with a seam, the shared
source with a mark per run, two columns of one run each, alignment by
line and by variable, `only here` and `differs`, each run's frame as bytes
(`hexdump` `eight`, by the frame's fields, a byte stored past its field
keeping that field's ink), the shadow beside an ASan run's rows, one clock with two moment counts, each pane's minimap at a
fortieth, the stopped side holding, a run's stderr as a panel; steps
matched by source line or loop turn.
9. **The introduction's blocks** ([`segments`](#segments), [`aligned`](#aligned)):
`segments` from the mappings: the whole (a bar, its two ends' addresses
and its size, every mapping a 2-unit line at its end); a box for each
cluster with the two lines of its magnification; its names, a row for
each edge and each band, rows 24 apart pooled round their edges, the
leaders; the program by segment, every other file once, permissions in
the row or inside a band 28 tall, nothing named under 6; rsp's and rip's
pins; a dump's place (the bracket and the standing `link` over the
stage's top); `ink`'s echo on a band and its row; treatments B and C as
options. `aligned` in its two forms, `interleaved` and `columns` (the
seam set by the longest line in the window, both places 132 into their
columns, cells as tall as their runs, the lines with no code in source
order). The verbs `regroup` (walked, and at a run), `ink`, `enlarge`,
`column`, `frame up`, `decode`, `align` (also between the two forms of
`aligned`). A hexdump with no ink (the first picture only), and a word
field ranged right, eight pairs wide. **The introduction as one scene**
(motion.md's storyboard): the three scenes and a fourth, the registers,
joined into one (`intro`), its chapters in the order I, II registers,
III the stack, IV code; a `chapter`'s title said at its seam (`title`) and
kept as the clock's label; one clock over one recording, from its first
stop and only forward, on from II2; the registers built with every
register a row and folded on a beat (`fold`, the dive's fold as a verb of
its own); `reg`'s `parts` with `unpack` and `pack`; a call stepped over
(its result struck first, then the wave); `segments`' live pins each on
its beat with `ink`'s echo; the dump folded to the shelf while the
working frame stands (I4's shelf, lent) and unfolded at the stack's rows;
code rows with no panel round them until a later `frame up`; the
registers' one set across the chapters (11 rows), so that III's stack is
356 to 868 and its program column main's rows 604 to 700 over reverse's
six, 712 to 888 (the three videos' II had eight rows of registers and
seven of reverse).
10. **Still from before**: the calls tree's small size and folds,
`metric.span.name_max` 300, `time.caption_max` 12 s and
`time.first_step` 4 s (5 s when a scene opens on the map), `time.dive`
and `time.flash`.
11. **Each pane's minimap** ([the minimap](#the-map-and-the-minimap)),
in place of the corner one: a strip inside each pane's frame drawn from
its column of the map, at the fixed scale, scrolled round the window;
its window, marks and arcs' ends; `flash` there; the pane's content 48
narrower and the disassembly's annotation at 540; the window gliding
with `scroll` and a far jump shown on the strip before the pane fades
through; `dive` and `surface` squeezing each column into its strip and
back; the clock's count at 1856. The corner minimap and its `K = 1/20`
go.
12. **The frame reworked** ([the frame](#5-the-frame)): the disassembly
under the source in every split, `blocks` included (no view: its
drawing over the program column, 880 by 344; the source six lines, the
disassembly eleven; the registers and a stack of twenty from the state
column's top); the source eight lines with any other lens; the
disassembly eleven as the subject; the registers `quiet`
([registers](#registers)): the scene's set found once from the
recording (the registers any of its moments changes, with rsp, rbp,
rip), the rest three to a row on a pitch of 285 under a rule, a quiet
cell's name faint at 12 and its value at 60 with `more` for a pointer;
the panel as tall as its rows and the stack taking the rest (`Split`'s
stack and registers from the scene, not fixed per split); the stack's
middle half for its scroll; the loupe from the view over the stack's
first six; in the `dive`, the registers folding as they land.
13. **A pane and its column, in motion** ([the minimap](#the-map-and-the-minimap)):
`unroll` and `roll`; a far jump in the same column by `unroll`, the
window travelling, `roll` (in place of a fade through); the strip's
window resizing with its pane in a `relayout`; every strip change 6 f
after the primary onset it follows.
14. **The disassembly tied to the stack** ([`insn`](#insn), [`slot`](#slot),
[`touch`](#4-ties)), the scene's knob `annotation` (`.tied`, the default;
`.whole`, today's rows), settable per beat. Under `tied`: an access's
annotation as the touched word's name (its slot's role, a global's
symbol) and its value, one hop, the name bold in its region's ink; a
register-setter cut after its first value; the fallbacks of the
annotation's table (an unnamed slot by its address, a word a dump holds
by its address, a word no pane holds whole); a direct call as
`reverse()`; `= &buf` for a `lea` of a named word; pushes and pops named
by the word's role. The stack's offset column from the frame's base, the
CFA's register at the newest frame's pc (rbp in a body; rsp at entry, in
a prologue before `mov rbp, rsp`, after `pop rbp` or `leave`, in a
function without a frame pointer), crossfading (12 f) when the base
changes, the tag saying which; the window over a leaf's red-zone locals.
The `touch`: 2 units in the mark's colour, out of the disassembly's
right rule at the row, the gutter's middle lane (x 956), onto the stack's
rule at the word; drawn in memory's slot before the word reacts (12 f,
18 past six rows), back with the advance; the first line to give way to
its echo. A load's read before the register it fills. A store of an
unchanged value: the arm's frame without a strike. The order of every
step cause to effect (the row, its touch, the word, then what follows
from it), nothing downstream armed early. **The stack pointers' moves**
([stack](#stack), [`travel`](#6-verbs), [`follow`](#6-verbs)): the
window's headroom of two `free` words over rsp; the rows holding while
rsp's or rbp's pin travels (24 f, 6 f a further row, 48 at most), its
amount counting on it, the rows it crosses gained or released, the
vermilion bracket over them, the span riding it, the register struck as
it lands; the window following only after, or under the pin in one move
for a climb longer than the room, or by `unroll` past the window; the
instruction's own annotation saying the move (`rsp -0x18 3 words`,
`rbp = rsp`, `rsp +8 · saved rbp`); at a run the pins over the veil.
15. **The column** ([column](#column)), now a form every scene may use, per
scene or per beat, the working frame its default. Built (`column`,
`column_sort`): the two columns, the shelf, the bubbles level with their
rows, the placements, the scene API. To fix, as the renders show them:
**a pane that stays and resizes keeps its rows** (the descent was drawn
empty for about 40 f while it grew: its frame must glide with its rows
in it, rows lost at the moving edge fading as it reaches them, rows gained
fading in behind it); **no panel crosses another in a change of form**
(the working frame's panels slid over each other, empty, on the way into
the column, and the graph shrank with its tag's note over the shelf on the
way out of it in `column_sort`): the leaving panes fold to the shelf in
place first, then the stayers move, a drawing scaling as one inside its
box; **an `on` bubble is placed and checked by the renderer** (16 clear of
every element and every path the beat's marks take; else `above`), not by
the scene; **a bubble about a folded pane points at its tag**; and the
instruments' CAPTION check extended to bubbles: a bubble whose reading
time is longer than its lead, its beat's steps and an 84 f hold is
flagged (the 104-character one left AIR of 4.9 s at 28.9 s), unless the
scene marks the rest as held. Then the two scenes motion.md storyboards
for it: the ASan pair and the introduction.
16. **The carry** ([`carry`](#4-ties)), a scene's knob `carry` (`.off`,
the default; `.arrow`; `.value` for a walked load; `.after_touch` for the introduction's push):
2 units in primary, an open chevron, the gutter's right lane, from the
source's read to the destination's strike; with `tied`, a load's touch
withdrawing as its carry leaves the word, a store drawing its carry and
no touch; nothing for a move between registers; a stub to a folded or
off-window end.
17. **Relations as one system** ([ties](#4-ties)), built as data: per frame,
the tables of places and of values, the kinds' table as the catalogue
gives it, relations as joins between them, and the resolver as a pipeline
of passes (candidates, knobs, priority, budget, route, draw), each pass a
loop over a table; the cost within 1 ms on the map. The new kind, `aim`
(off by default, the author's): code's ink, the gutter's left lane, the
row's address framed; held, moved or frayed as its word is written.
**What the recordings must hold**, with the tracer's options:
- For the map, as before: `--stack 1024`, `--disasm 69`, `--around 256`;
the source file, the frame chain, the allocations, the call frame
information, the locals' places, the first stack pointer.
- **For a descent**, at every stop: the backtrace by the unwind tables (in
since this round, by the tracer's note; the build this round's mocks
were made with still lost `main` at the first instruction of `open`,
`#1 libc.so.6+27781`); for each frame the module, whether it has
source, its function's bounds, and three instructions round its call
row (the return address and the instruction before it); names at every
pc, the first instruction of a function too (`open`'s entry printed
bare, `7ffff7d10ec0`, where its middle printed `libc.so.6!open+261`);
a PLT stub by its symbol (`open@plt`, not `hello+1070`) and its GOT slot
(`open@got`) with the slot's value at the stop; whether the slot is
still lazy.
- **For a crossing**, at the `syscall` row: the number and its name, the
arguments by the call's signature (a descriptor with what it is open
on, a path or a buffer with its bytes, flags by name), the result, the
registers it clobbered.
- `ztrace record --by insn --from main` began in the loader with the
ReleaseFast build used here (`hello`, 120 moments, all in `ld.so`):
`--from` did not take; `dbg` with a breakpoint was used instead.
- **For `tied`**: the touches of the stack's own instructions, which the recording leaves out today
(`push`, `pop`, `call`, `ret`, `leave`, `enter`: the word, its size, read or write; the explicit operands'
touches are there, `ztrace dump`'s `touch` events); data symbols by name (`head` at 404018), for a
global's annotation; the roles at every pc of a prologue and an epilogue (today a local is found only
where the frame base is the CFA's register, so `prev` and `cur` come after `mov rbp, rsp`: right, but the
saved rbp's role must be there from the `push`); a local's own offset and size where two share a word
(`f, low half` and the return-value slot beside it); the canary's copy named as the place it is
(`the stack's canary`, from the `fs:[0x28]` load that stored it). `ztrace show` prints none of the roles;
`telescope.slots` has them.
- For the heap scene: see [the scene](motion.md#a-scene-libcs-heap-from-the-inside).
- For a pair (the ASan scene): see [the scene](motion.md#a-scene-asan-against-a-plain-build).
- For the introduction: the mappings with their permissions and their
file offsets (to say code, read-only data, data): `ztrace show` prints
them now (this round's recording of `targets/list` under `env -i setarch
-R`; the kernel now splits `[vvar]` in two, `[vvar_vclock]` its second
page pair); the bytes of the
instructions in the window (or the binary, for the renderer to read
them); and a recording of the program by instruction from `main` to the
stop, so that a real `push`, a real `call` and the moment rsp moves are
shown, not described. **Its chapter on registers** needs the recording
to start earlier and to be the program's alone. From `list.c:40`,
main's `push(9)` (in place of `:41`, its `reverse()`), to `list.c:22` as
now: so that push(9) at line 11 is in it, its `mov edi, 0x10` and
`call malloc@plt`, a call that takes an argument and gives a result (push
is `void`, reverse takes nothing: malloc is the one real call with both
before reverse), and every instruction of malloc by instruction (162 in
this round's run), which the chapter steps over and the clock counts.
Chapters I, III and IV are found by name as now (`reverse`'s first
moment, the load on line 21) and do not move. Without the agent's
preload: its malloc wrapper leaves its own values in rsi, rdi and r8 to
r11 (the present recording's rdi at reverse's entry, `7ffff5c011e8`, lies
in no mapping a run without the agent has; that run's is 4), so the step over the call would strike eight registers,
four of them the tracer's and not the program's, where glibc's malloc
alone changes rax, rcx, rsi and rdi (and r11's word); IV's nodes then
take their chunks from `--heap` (glibc's heap at each stop) rather than
the agent's allocations. Every register at each stop as now; the stack's
1024 bytes as now (the 128 bytes are the same words at reverse's entry);
the clock's count from the first stop at line 40 (the start-up's system
call stops before it are not the program's steps). Each register's
parts' names are the renderer's own table (`reg`'s `parts`).
- **For the graph**, per function and once: its blocks (first and last
address, how each ends: a conditional jump, a jump, an indirect jump, a
return, a call that does not return, or a fall into the next), each
block's edges with their kind and target, the calls in it and their
callees, and an indirect jump's table where it can be read. Calls that
do not return must be known by name (`__stack_chk_fail`,
`__syscall_do_cancel`, `abort`, `exit`), and instruction prefixes
(`addr32 call`, `notrack jmp`, `bnd jmp`) read through, or a block runs
on into the next and makes a false loop (it did in this round's first
try at libc's `open`). Per stop: the visits to each block and the count
of each edge so far (the renderer can count them from the `branch`
events, if every taken branch and fall-through between blocks is
there), and, for the folds, which blocks the whole recording ever
reaches. For a descent in graph form, each frame's function's blocks.
## Token changes
Against `anim/src/theme.zig`: "In theme.zig" is what is in the file, "Is"
what the documents say. The first seven rows are this round's, read on 11
November at 14:15; the rest were read on 10 November at 23:07, and some
may be in since (the pane's `strip` is: the corner minimap's row below is
done). The map's, the loupe's and the arc's tokens, the lift's colours,
and `metric.bytes` and `metric.slot`'s new columns are in, as asked.
| Token | In theme.zig | Is |
| --- | --- | --- |
| `layout.split` | `beside` (152, 152, 8 lines, 17, 8 slots, 5); `subject` (296, 200, 10, 9, 6, 7); `blocks`: `subject` with the disassembly 7 rows over the state column and the source 20 | `none` (14 lines, 17; registers, the stack the rest, a backtrace of 4 at the foot); `beside` (152, 152, 8, 17, 5); `subject` (296, 200, 8, 11, 7); `blocks` (a drawing of 880 by 344 over the program column and no view; 6, 11; the state column from the top). In every split the registers are `registers.rows` high and the stack has what the state column has left, on the 24 grid, any rest above it: `Split` takes the scene's register rows |
| `metric.registers.quiet` | none | three to a row, pitch 285 from 12; the name faint at 0, the value at 48 (60 from the panel's edge); a pointer's chain cut to `more` at once; a 2-unit `rule` over the first quiet row; rip last |
| `metric.graph` | the layered form's: layers 48 apart, blocks 56, lanes 16 from 24, back edge down 14, ports 40, arrivals 48, the channel 32, corners 8; the lens's boxes 24 high, 60 and 10 a row, columns 300 apart, layers 12, lanes 10 | a block a pill 24 high, ends round: offset at 12, calls after it faint, visits ranged 12 from the end; 12 apart at least. `rings`: header at 9 o'clock, clockwise; radius as its pills need (sort: 140 and 84); a nested ring outside its parent at the parent's 3 o'clock; a fork inside 30 in; a way out from 30 in from the pill's far end, bends of 16; the turns 30 under the centre (mono 20 and Go 18 `turns`). `layers`: layers 12, lanes 10, columns 300, every corner a quarter circle of 12. Heads 8 by 8. A fold dashed 12 on 8. The pane: 880 by 344. Gone: the boxes with rows on the map, their lanes and channels |
| `time.leave` | chips 0.30, the edge 0.30, the mark 0.20 and 2 f a 100 units, 0.50 at most; count 0.10, trail 0.30, rest 0.70, at a run 0.13 | the same along arcs (sort's steps round a ring are 58 to 72 units: 12 f; its inner way out 318: 18 f); `turn` the same round the ring's foot, the count at its centre armed as the mark leaves the latch and struck as it lands |
| `time.reach` | none | the edge drawn gold under the mark (the `leave`'s own); the pill from the page to `raised` 0.20 as the mark lands, its offset brightening, `×1` fading in 0.10 and struck |
| `time.unfold` | none | the pills beyond make room 0.40 (`glide`, round the ring or down the layers), the fold's blocks fade in 0.20, quiet, 0.033 apart, then the reached one's `reach` |
| `time.unroll` | none | `unroll` 0.60 (`glide`), held 1.00 at least, `roll` 0.60; a far jump: `unroll`, the window's travel 0.40, `roll` |
| `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.calls` small, folds | full only | disc 36, level 38, badge 24 at 6 and 32, mono 20; fold past 13 leaves or 6 levels |
| `metric.width` | none | cells 5 by 10, 7 apart, `dim`, standing on the baseline 3 after the `]`; what follows 4 after the last cell; eight cells and a count past 8 bytes |
| `metric.insn.wide` | none | 12 a digit past seven, per window: libc's mnemonic at 240, its annotation at 624 |
| `metric.descent` | none | callers' windows 3 rows; a head a row (rule 2, name at 40 in Go Medium 18, what it is ranged right in Go 18); the call lane at x 14, 2 in primary, head 7 by 8 into the name; into the kernel 3 in vellum, its head in ink; three windows of code, then a fold row; the kernel's window a head and two rows |
| `metric.node.two_rows`, `metric.bin` | none | rows 110 apart, nodes 136 wide; the bin box 160 by 44 at the row's left, its count on a 30 square on the shoulder; a free node's outline dashed 12 on 8 |
| `time.descend` | none | `close` 0.20 then 0.30 (`glide`), `ring` 0.20, `lane` 0.30, `head` 0.20, `rows` 0.20 a row 0.03 apart, from 1.10 after the fire, the given-up rows fading before the kept glide, never both; from 1.80 after the fire once the push is in cause order (touch, word, rsp's pin, the window following); the step 3.60 |
| `time.cross` | none | the registers framed 0.10 apart from 0.30; `lane` 0.40 from 0.80; the kernel's window 0.20; the answer up 0.40; the step 3.60, 4.90 when it moves bytes |
| `time.ascend` | none | `close` 0.20 a row, 0.03 apart, from 1.60 (after the touch, the read, rsp's pin falling and the window following); the lane back 0.20; the caller's kept rows 0.30 (`glide`), then the given-back rows 0.20; the step 3.30 |
| `metric.segments` | none | the whole 20 wide, the stage's height, its labels 12 left of it; a box 180 wide (108 in a column of 880), framed 2 out, 48 apart; bands 30% over the page, named from 6 tall, permissions inside from 28; the names 64 past the box, rows 24, a band's row indented 24, sizes ranged right 132 in, files at 252 on a bracket at 240; leaders 8 out, 20 short, 12 in; the magnification 2 `rule`; a dump's place: its link 3 in the stack's ink over y 56, standing at 60% toward the page; for a visit, a 2-unit tick across the box and its size in Go 20, the stack's ink |
| `time.enlarge` | none | the line framed 0.10; the ride 1.20 (`glide`); page lines 0.20; names 0.20 each, 0.033 apart, a leader 0.10 before its address; the next cluster as one lands |
| `time.regroup` | none | the rows in 0.30 each, 0.30 apart; rows making room 0.30, down 0.20, left 0.30; veil 0.30; offsets 0.20 each, 0.033 apart; a byte's flight 0.40, 0.30 apart (one in the air at a time), 40 over its row, its offset 22 over it; the gaps 0.20; the zeros 0.20; at a run a word 0.133, rows 0.10 apart; the dump's fold 0.40 and 0.40 |
| `insn.annotation` | none (the chain always) | `tied` (the default) or `whole`, a scene's, settable per beat |
| `metric.slot.offset` | from rsp | from the frame's base (the CFA's register at the newest frame's pc) under `tied`; the tag's note names it; a change of base crossfades 0.20 |
| `metric.touch` | none | 2, in the mark's colour; the gutter's middle lane at 956; a head 7 by 8 on the stack's rule (on its right rule, pointing left, in the column); corners 6 |
| `time.touch` | none | 0.20 (0.30 past six rows), `standard`, in memory's slot before the word's arm or frame; back 0.20 with the advance; none at a run |
| `metric.stack.headroom` | none (the window's top is rsp) | two `free` words over rsp at rest |
| `time.sp_travel` | `time.pin` (24 f, 2 f a row, 36 at most) for every pin | rsp's and rbp's: 0.40, 0.10 a further row, 0.80 at most (`glide`); the amount's crossfade 0.20 at the advance; a row's gain or release 0.20; at a run 0.13, 0.03 a row, 0.27 at most |
| `time.follow` | none | after the landing: 0.40, 0.03 a further slot, 0.60 at most (`glide`) |
| `metric.carry`, `time.carry` | none | 2 in primary, an open chevron 7 by 8 in two strokes; the gutter's right lane, 962; the source's read 0.10, the arrow 0.30 (0.40 past eight rows), the destination's arm 0.20 and strike, back 0.30 with it; `carry = .value`: a chip of `raised`, mono 20, on the head |
| `metric.aim`, `time.aim` | none | 2 in code's ink, a filled head 10 by 10 on the disassembly's right rule, the row's address framed 2 in code's ink; the gutter's left lane, 950; 0.30 (0.40 past ten rows), `standard`; a new row 0.40 (`glide`); fraying: dashed 0.20, out 0.30; standing at 60% |
| `relations` | each kind its own | the kinds' table ([ties](#4-ties)); the budget: the thread, two active, one standing across panes; the pass within 1 ms on the map |
| `metric.column` | none | the panes at 64 and the text at 976, 880 each; the shelf at 48, 24 high, its tags 12 apart; the panes from 84, narrated rows above 888, the floor to 1032; the clock under the text column at 900 |
| `metric.bubble` | none | Go 40 on 54, code mono 35; 40 characters and three lines at most (80 and two `above` a subject across both columns); padding 16, 812 wide at most; the newest on `raised`, older ones `dim` and bare; three at most; 12 between bubbles; the stem 2 in `dim`, a head 7 by 8 |
| `time.bubble` | none | in 0.30 rising 8 (`enter`), out 0.20; dim 0.30; out of the newest's way 0.40 (`glide`); the stem 0.20 in with the bubble, 0.20 back with the fire; between beats: fold 0.20 then 0.40 (the panel closing as its tag travels to the shelf), the stayers 0.40, unfold 0.40 (the tag back as the panel opens) then 0.20 |
| `metric.aligned` | `interleaved` only | `columns`: the seam 48 after the longest line in the window; each column's place ranged right 132 into it, its text 24 after; a line's first row `raised` |
| `metric.parts` | none | the row's eight bytes from 72 on a pitch of 30, high first, `pad` at 45%; a part's row under it, widest first: a 2-unit `dim` bracket under its bytes, 3 out from the first and last, serifs 11 up; its name ranged right 10 before the bracket, mono 20 `dim`; three rows (four with `ah`) |
| `time.unpack`, `time.pack` | none | `unpack`: the rows make room 0.30 (`glide`), the bytes spread 0.20, the parts 0.20 each, 0.10 apart; `pack`: the parts out 0.20, then the bytes close and the rows close up 0.40 (`glide`) |
| `time.fold` | inside the dive's move | 0.60 (`glide`), the chains past the first hop out over its first 0.40, then the rule 0.20 |
| `time.call_over` | none | the arguments read 0.10 apart from 0.30; still 0.20; rax armed 0.20 and struck at 0.80; the annotation's result 0.10; the wave from 1.10, 0.033 apart; hold 0.60; the step 2.4 with a wave of three |
| `time.title`, `metric.chapter` | none | from the frame the last text is read: still 0.50; the texts out 0.20; the title in 0.30 at 0.80, rising 8; still 1.00; the opening from 2.10; the title out at its reading time or the opening's end; Go Medium 40, the numeral `faint`, the name `bright`; the label Go 18 `faint`, 24 left of the clock's count, crossfading 0.20 |
Unchanged and already there: the 1920 stage (its splits change, above), each pane's `strip`, 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 four splits (the registers `quiet`) and `relayout`; the camera at x1.5.
8. The other lenses in the band.
9. The map and the minimap; `dive` and `surface`; the loupe.
10. Operands without size words and `width`; the row's detail; the
`descent` and `descend`, `cross`, `ascend`; malloc's words; `nodes` in
two rows.
Export:
```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.
|