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
|
#!/usr/bin/env python3
"""The introduction: the frame built from its bytes up, on the recording of targets/list that mocks 9 to 21 use
(list-dbg.txt: the stack from rsp, the heap, the registers; the code's bytes from objdump of the binary; the
mappings from `ztrace show` of a fresh recording of the same build). Instants of the build, each as the camera
frames it, and the blocks it introduces: `segments` (34, its treatments 35), `aligned` in its two forms (33, 36),
`regroup` walked (37).
python3 -B intro.py # 29-intro-bytes ... 37-regroup (.svg)
"""
import gen
import dense as D
import context as C
from context import (PAGE, RAISED, RULE, VELLUM, BRIGHT, DIM, FAINT, GOLD, KW, CODE, STACK, DATA, HEAP, READ,
A, S, ROW, TAG, PAD, MONO, BOLD, b, ph, mix, Svg)
RSP = D.RSP
END = 0x800000000000 # the user half's end: 7fffffffffff + 1, 128 TiB
# The mappings at the stop, low to high, as `ztrace show` prints them (range, permissions, file); the kernel's
# [vsyscall] page is above the user half and not drawn. A fresh recording of the same build under `env -i
# setarch -R` (the kernel now splits [vvar] in two; nothing else moved).
MAPS = [(0x1000000, 0x1001000, "r--", "list"), (0x1001000, 0x1002000, "r-x", "list"),
(0x1002000, 0x1003000, "r--", "list"), (0x1003000, 0x1004000, "rw-", "list"),
(0x1004000, 0x1025000, "rw-", "[heap]"),
(0x7ffff7c00000, 0x7ffff7c24000, "r--", "libc.so.6"), (0x7ffff7c24000, 0x7ffff7d9f000, "r-x", "libc.so.6"),
(0x7ffff7d9f000, 0x7ffff7e15000, "r--", "libc.so.6"), (0x7ffff7e15000, 0x7ffff7e19000, "r--", "libc.so.6"),
(0x7ffff7e19000, 0x7ffff7e1b000, "rw-", "libc.so.6"), (0x7ffff7e1b000, 0x7ffff7e23000, "rw-", ""),
(0x7ffff7f70000, 0x7ffff7f75000, "rw-", ""), (0x7ffff7f75000, 0x7ffff7fb6000, "r--", "ld.so.cache"),
(0x7ffff7fb6000, 0x7ffff7fba000, "r--", "[vvar]"), (0x7ffff7fba000, 0x7ffff7fbc000, "r--", "[vvar_vclock]"),
(0x7ffff7fbc000, 0x7ffff7fbe000, "r-x", "[vdso]"), (0x7ffff7fbe000, 0x7ffff7fbf000, "r--", "ld.so"),
(0x7ffff7fbf000, 0x7ffff7fec000, "r-x", "ld.so"), (0x7ffff7fec000, 0x7ffff7ffb000, "r--", "ld.so"),
(0x7ffff7ffb000, 0x7ffff7ffd000, "r--", "ld.so"), (0x7ffff7ffd000, 0x7ffff7ffe000, "rw-", "ld.so"),
(0x7ffff7ffe000, 0x7ffff7fff000, "rw-", ""), (0x7ffffffde000, 0x7ffffffff000, "rw-", "[stack]")]
INK = {"r-x": CODE, "r--": VELLUM, "rw-": DATA}
def ink_of(a):
"""The ink of the mapping a is in (None: none)."""
for lo, hi, perm, name in MAPS:
if lo <= a < hi:
return STACK if name == "[stack]" else HEAP if name == "[heap]" else INK[perm]
return None
# The three clusters: what each enlargement spans.
CLUSTERS = {"stack": (0x7ffffffde000, 0x7ffffffff000), "libraries": (0x7ffff7c00000, 0x7ffff7fff000),
"program": (0x1000000, 0x1025000)}
def runs_of(lo, hi):
"""The bands an enlargement names: its mappings, touching ones of one file and one permission as one (a
file's anonymous rest, its bss, with the file's rw-). Low to high: (lo, hi, perm, file)."""
out = []
for lo_, hi_, perm, name in MAPS:
if hi_ <= lo or lo_ >= hi:
continue
if out and out[-1][1] == lo_ and out[-1][2] == perm and (out[-1][3] == name or not name and out[-1][3]):
out[-1] = (out[-1][0], hi_, perm, out[-1][3])
else:
out.append((lo_, hi_, perm, name))
return out
def files_of(lo, hi):
"""The bands named by file: a file's mappings as one (its anonymous rest with it), the vDSO with its data; its
permissions when they are one for the whole file (the stack, the heap), else None. Low to high."""
out = []
for lo_, hi_, perm, name in MAPS:
if hi_ <= lo or lo_ >= hi:
continue
name = "[vdso]" if name.startswith("[vvar") else name
if out and out[-1][1] == lo_ and (out[-1][3] == name or not name and out[-1][3]):
out[-1] = (out[-1][0], hi_, perm if out[-1][2] == perm else None, out[-1][3])
else:
out.append((lo_, hi_, perm, name))
return out
def size(n):
"""A size in its largest whole unit: 132 KiB, 1.5 MiB, 128 TiB."""
for unit, k in (("EiB", 1 << 60), ("PiB", 1 << 50), ("TiB", 1 << 40), ("GiB", 1 << 30), ("MiB", 1 << 20), ("KiB", 1 << 10)):
if n >= k:
v = n / k
return ("%d %s" % (round(v), unit)) if v >= 10 or round(v, 1) == round(v) else "%.1f %s" % (v, unit)
return "%d B" % n
def spread(ideal, pitch, lo, hi):
"""Rows wanting to be at `ideal` (in order, top down), at least `pitch` apart, each as near its want as the
others let it (adjacent rows pooled at their mean), the whole kept inside lo..hi."""
groups = [] # [first index, count, top]
for i, y in enumerate(ideal):
groups.append([i, 1, y])
while len(groups) > 1 and groups[-2][2] + groups[-2][1] * pitch > groups[-1][2]:
b_, a_ = groups.pop(), groups.pop()
n = a_[1] + b_[1]
top = sum(ideal[a_[0]:a_[0] + n]) / n - (n - 1) * pitch / 2
groups.append([a_[0], n, top])
out = [g_[2] + k * pitch for g_ in groups for k in range(g_[1])]
for i in range(len(out) - 1, -1, -1): # then inside the bounds: up from the foot, down from the top
out[i] = min(out[i], hi if i == len(out) - 1 else out[i + 1] - pitch)
for i in range(len(out)):
out[i] = max(out[i], lo if i == 0 else out[i - 1] + pitch)
return out
def whole(g, x, y0, y1, w=20, labels=True):
"""`segments`, the whole: the user half, 0 to 7fffffffffff, to scale in a slim bar. Every mapping is where it
is, and at this scale that is a 2-unit line at one end or the other. Its ends and its size, nothing else."""
g.frame(x, y0, w, y1 - y0, DIM, 2)
g.rect(x + 2, y0 + 2, w - 4, 2, STACK) # the stack, its 132 KiB at the very top
g.rect(x + 2, y0 + 4, w - 4, 2, CODE) # the libraries, 128 MiB under it: the same line
g.rect(x + 2, y1 - 6, w - 4, 2, HEAP) # the heap over the program, 16 MiB above 0
g.rect(x + 2, y1 - 4, w - 4, 2, CODE)
if labels:
C.addr(g, x - 12 - 12 * A, y0 - ROW / 2, END - 1, DIM)
g.t(x - 12, b(y1 - ROW / 2), "0", S, DIM, MONO, "end")
g.t(x - 12, b((y0 + y1) / 2 - ROW / 2), size(END), S, DIM, MONO, "end")
return {"stack": (x + w, y0 + 3), "libraries": (x + w, y0 + 5), "program": (x + w, y1 - 4)}
def enlargement(g, x, y, w, h, lo, hi, live=(), perms=(), hot=()):
"""`segments`, magnified: lo..hi to a linear scale, high on top. Each mapping a band in its ink a third of the
way over the page; a change of permission is a change of ink, a new mapping of one file a 2-unit page line
where both are 6 tall. Permissions written inside a band 28 tall or more. live: pins (name, address)."""
yof = lambda a: y + h - (a - lo) / (hi - lo) * h
g.frame(x - 2, y - 2, w + 4, h + 4, DIM, 2)
last = None
for lo_, hi_, perm, name in MAPS:
if hi_ <= lo or lo_ >= hi:
continue
ink = ink_of(lo_)
y0, y1 = yof(hi_), yof(lo_)
g.rect(x, y0, w, max(y1 - y0, 2), mix(ink, PAGE, 0.3))
if last and last[0] == lo_ and y1 - y0 >= 6 and last[1] >= 6:
g.rect(x, y1 - 1, w, 2, PAGE)
if any(a <= lo_ < z for a, z in perms) and y1 - y0 >= 28: # a mixed file's parts: their permissions inside
g.t(x + w / 2, (y0 + y1) / 2 + 7, perm, S, VELLUM, MONO, "middle")
last = (hi_, y1 - y0)
if any(lo_ <= a < hi_ for a in hot): # `ink`'s echo: the mapping a word points into, framed as read
g.frame(x + 4, y0 - 6, w - 8, max(y1 - y0, 2) + 12, READ, 2)
for name, a in live: # a register's pin, under what it points to, in its band
py = yof(a)
C.pin_up(g, x + 24, py, [None, name], ink_of(a) if name != "rip" else CODE, S)
return yof
def table(g, x, w, yof, runs, col, lo_b, hi_b, pins=None, hot=()):
"""The enlargement's names, right of its bar. A band 6 tall or more is named: a row for each of its edges (the
address, in the ink of the band it bounds, a leader from the edge to it) and between them a row for the band
(permissions, size), indented under the addresses; the bands of one file share its name, on a bracket right
of their rows. Thinner bands are drawn and not named. Rows 24 apart, each as near its place as the others
let it. pins: {address: name}, a register's pin at the end of its band's row; hot: addresses whose band's row
is framed as read (`ink`'s echo)."""
named = [r for r in runs if yof(r[0]) - yof(r[1]) >= 6]
rows = [] # (kind, ideal y, payload), top down
for lo_, hi_, perm, name in reversed(named):
if not (rows and rows[-1][0] == "edge" and rows[-1][2][0] == hi_):
rows.append(("edge", yof(hi_), (hi_, lo_)))
rows.append(("run", (yof(hi_) + yof(lo_)) / 2, (lo_, hi_, perm, name)))
rows.append(("edge", yof(lo_), (lo_, lo_)))
ys = spread([r[1] for r in rows], ROW, lo_b, hi_b)
files = {}
for (kind, iy, p), ry in zip(rows, ys):
if kind == "edge":
a, of = p
ex = x + w + 2
if abs(ry - iy) < 1:
g.path(f"M{ex},{iy} H{col - 8}", RULE, 2)
else:
g.path(f"M{ex},{iy} h8 L{col - 20},{ry} H{col - 8}", RULE, 2)
C.addr(g, col, ry - ROW / 2, a, ink_of(of))
else:
lo_, hi_, perm, name = p
xx = col + 2 * A
if any(lo_ <= a < hi_ for a in hot):
g.frame(xx - 6, ry - ROW / 2, 12 * A, ROW, READ, 2)
if perm:
g.t(xx, b(ry - ROW / 2), perm, S, DIM, MONO)
g.t(xx + 11 * A, b(ry - ROW / 2), size(hi_ - lo_), S, DIM, MONO, "end")
files.setdefault(name, []).append(ry)
for pa, pn in (pins or {}).items():
if lo_ <= pa < hi_:
px = xx + 11 * A + 12
g.path(f"M{px},{ry} l9,-6 v12 Z", fill=ink_of(pa))
g.t(px + 14, b(ry - ROW / 2), pn, S, VELLUM, BOLD)
bx = col + 19 * A + 12 # the files: a bracket over their rows, the name beside
for name, rys in files.items():
if len(rys) > 1:
C.bracket(g, bx, min(rys) - 8, max(rys) + 8, RULE, 2, 5, side=-1)
g.t(bx + 12, b((min(rys) + max(rys)) / 2 - ROW / 2), name, S, VELLUM, MONO)
else:
g.t(bx + 12, b(rys[0] - ROW / 2), name, S, VELLUM, MONO)
return ys
def magnify(g, ax, ay, x, y, h):
"""The two lines of a magnification: from the place on the whole to the enlargement's corners."""
g.path(f"M{ax},{ay} L{x - 2},{y - 2} M{ax},{ay} L{x - 2},{y + h + 2}", RULE, 2)
EW = 180 # an enlargement's width
def segments(g, wx, wy0, wy1, ex, boxes, col, says="all", live=True, bounds=None, hot=(), ew=EW):
"""`segments`: the whole as a slim bar at wx, and an enlargement of each cluster at ex (boxes: name -> (y, h)),
its names from col. Returns each enlargement's yof and x, for ties."""
apex = whole(g, wx, wy0, wy1)
out = {}
for name in ["stack", "libraries", "program"]:
lo, hi = CLUSTERS[name]
y, h = boxes[name]
magnify(g, *apex[name], ex, y, h)
runs = (runs_of if says == "all" and name == "program" else files_of)(lo, hi) # the program by segment
yof = enlargement(g, ex, y, ew, h, lo, hi, [("rsp", RSP)] if live and name == "stack" else (),
[(r[0], r[1]) for r in runs if r[2] is None], hot)
lo_b, hi_b = (bounds or {}).get(name, (y - 200, y + h + 200))
table(g, ex, ew, yof, runs, col, lo_b, hi_b, {0x1001926: "rip"} if live else None, hot)
out[name] = (yof, ex)
return out
BOXES = {"stack": (72, 72), "libraries": (196, 368), "program": (612, 252)}
BOUNDS = {"stack": (60, 156), "libraries": (184, 588), "program": (600, 876)}
EIFFEL = [[("If this bar were the Eiffel Tower, all that is mapped would be",)],
[("7 µm thick: a tenth of a hair, split between its two ends.",)]]
def treatment_a(g):
"""A: the whole, and each cluster enlarged: the program's segments each named with its two addresses,
permissions and size, under a bracket with the file's name; every other file once, its start, stop, size,
its parts' permissions inside the bands that have room; rsp and rip pinned."""
segments(g, 472, 72, 864, 972, BOXES, 1216, bounds=BOUNDS)
gen.caption(g, EIFFEL)
def treatment_b(g):
"""B: the same, saying less: the program too is one file, named once; no pins."""
segments(g, 472, 72, 864, 972, BOXES, 1216, says="files", live=False, bounds=BOUNDS)
gen.caption(g, EIFFEL)
def treatment_c(g):
"""C: the whole alone. Each end's clusters one label each, where they start and how big; no enlargement."""
x, y0, y1 = 760, 72, 864
apex = whole(g, x, y0, y1, 24)
lx = x + 24 + 96
for (ax, ay), ly, a, text, sz in [(apex["stack"], y0, 0x7ffffffde000, "[stack]", 0x21000),
(apex["libraries"], y0 + 48, 0x7ffff7c00000, "libc.so.6, ld.so",
0x7ffff7fff000 - 0x7ffff7c00000),
(apex["program"], y1, 0x1000000, "list, [heap]", 0x25000)]:
g.path(f"M{ax + 2},{ay} h12 L{lx - 20},{ly} H{lx - 8}", RULE, 2)
C.addr(g, lx, ly - ROW / 2, a, ink_of(a))
g.t(lx + 13 * A + 7 * A, b(ly - ROW / 2), size(sz), S, DIM, MONO, "end")
g.t(lx + 21 * A, b(ly - ROW / 2), text, S, VELLUM, MONO)
gen.caption(g, [[("Everything mapped is at the two ends of this bar:",)],
[("128 TiB, and between them nothing.",)]])
def frame_space(name):
"""Mock 34: `segments` at full size, treatment A."""
gen.W, gen.H = 1920, 1080
g = Svg()
treatment_a(g)
g.save(name)
def sheet_abc(name):
"""Mock 35: three treatments of the address space, each as the frame it would be, saying less and less."""
gen.W, gen.H = 1920, 3 * 1160
g = Svg()
for k, (t, sub, draw) in enumerate([
("A", "each cluster enlarged; the program's segments each with its start, stop and size; every other "
"file once (recommended)", treatment_a),
("B", "each cluster enlarged; every file once, the program too: its start, stop and size; no pins",
treatment_b),
("C", "the whole alone; each cluster one label: where it starts, its size", treatment_c)]):
oy = k * 1160
g.rect(0, oy, 1920, 80, gen.RAISED)
g.t(64, oy + 54, t, 40, GOLD, "sansb")
g.t(120, oy + 52, sub, 24, VELLUM, "sans")
g.o.append(f'<g transform="translate(0,{oy + 80})">')
draw(g)
g.o.append("</g>")
g.save(name)
def camera(g, k, cx, cy):
"""The camera at scale k on the point (cx, cy) of the frame: all drawing after this is through it."""
g.o.append(f'<g transform="translate({960 - cx * k},{468 - cy * k}) scale({k})">')
def word_text(w):
"""A word as the stack writes it: an address bare; a number as the `value` atom writes it (a digit, `0x` and its
hex; a small number's decimal is left out here, as none is in these words)."""
return "%x" % w if ink_of(w) or w < 10 else "0x%x" % w
def raw_dump(g, x, y, rows, per=16, words=False, inked=False):
"""The stack's bytes from rsp, `per` to a row; with words, each row's eight bytes read right to left as the
word they make, beside them, in the ink of what it points into when inked. Returns the rows' y."""
ys = []
for r in range(rows):
a0, yy = RSP + per * r, y + r * ROW
ys.append(yy)
C.addr(g, x, yy, a0, STACK if inked else FAINT)
bx = x + 12 * A + 12
vals = [D.MEM.get(a0 + k, 0) for k in range(per)]
for k, v in enumerate(vals):
g.t(bx + k * 30 + (12 if k >= 8 else 0), b(yy), "%02x" % v, S,
mix(VELLUM, PAGE, 0.5) if words else VELLUM, MONO)
if words: # the word, ranged right in its field (its eight pairs as they land): low byte last
w_ = D.word(a0)
ink = (ink_of(w_) or VELLUM) if inked else VELLUM
g.t(bx + per * 30 + 24 + 8 * 30, b(yy), word_text(w_), S, ink, MONO, "end")
return ys
def frame_bytes(name):
"""The first picture: bytes, nothing else; the camera at x2 on them, where the stack panel will be built."""
gen.W, gen.H = 1920, 1080
g = Svg()
g.o.append('<g transform="translate(300,170) scale(2)">')
g.t(0, -10, "128 bytes at %x" % RSP, 18, FAINT, "sans") # nothing named before it is shown: no stack, no rsp
raw_dump(g, 0, 0, 8)
g.o.append("</g>")
gen.caption(g, [[("A running program is bytes in memory:",)],
[("here are 128 of them.",)]])
g.save(name)
def frame_words(name):
"""Mock 30: the `ink` beat. The words, eight bytes a row, in the state column where the stack will be; the
address space in the program column; the dump tied to its place at the top of the stack; the return
address, 10018b0, framed with the mapping it points into (an echo)."""
gen.W, gen.H = 1920, 1080
g = Svg()
top = 80
boxes = {k: (y + 8, h) for k, (y, h) in BOXES.items()}
bounds = {k: (a + 8, z + 8) for k, (a, z) in BOUNDS.items()}
bounds["stack"] = (top + 24, 172) # the tie comes in over the stack's top: its first row under it
out = segments(g, 224, top, 864, 368, boxes, 540, live=False, bounds=bounds, hot={0x10018b0}, ew=108)
dx = 1048 # the dump, where the stack panel will be
ys = raw_dump(g, dx, top, 16, per=8, words=True, inked=True)
bx = dx + 12 * A + 12
k = 1 # 7fffffffece8: the return address, main+80
g.frame(bx - 6, ys[k], 8 * 30, ROW, READ, 2)
g.frame(bx + 8 * 30 + 24 + 8 * 30 - 7 * A - 6, ys[k], 7 * A + 12, ROW, READ, 2)
# the tie: these 128 bytes are at the top of the stack. A bracket on the dump's rows, a `link` in the stack's
# ink from it over the top of the stage and down onto the stack's place, its head on it; standing now (its
# beat was the one before), so quiet.
yof, ex = out["stack"]
hx, ink = ex + 108 - 30, mix(STACK, PAGE, 0.6)
C.bracket(g, dx - 14, top + 3, top + 16 * ROW - 3, ink, 3, 6)
gen.arrow(g, [(dx - 14, top + 3), (dx - 14, 56), (hx, 56), (hx, top - 1)], ink, 3, r=8, hl=10, hw=10)
gen.caption(g, [[("A word takes the ink of the mapping it points into: ",)],
[("10018b0", "mono"), (" is in list's code, ",), ("1001000", "mono"), (" to ",), ("1002000", "mono"),
(".",)]])
g.save(name)
# ---- `regroup`, walked: the return address's eight bytes becoming its word ---------------------------------------
WALK = 0x7fffffffece8 # b0 18 00 01 00 00 00 00: 10018b0, main+80
BX = 12 * A + 12 # the bytes, 12 after the address
FR = BX + 8 * 30 + 24 + 8 * 30 # the word's field ends here, ranged right: its low byte last
def glide(t):
"""`glide`, the cubic (0.45, 0, 0.55, 1), by bisection on x."""
lo, hi = 0.0, 1.0
for _ in range(40):
m = (lo + hi) / 2
x = 3 * (1 - m) ** 2 * m * 0.45 + 3 * (1 - m) * m * m * 0.55 + m ** 3
lo, hi = (m, hi) if x < t else (lo, m)
m = (lo + hi) / 2
return 3 * (1 - m) * m * m + m ** 3
LIFT, OFF_AIR = 40, 22 # a byte flies 40 over its row; its offset rides 22 over it
def clamp01(x):
return min(max(x, 0.0), 1.0)
def flight(k, f):
"""Byte k at frame f of the beat: one in the air at a time, 24 f each, 18 f apart, the low byte first (motion.md,
"A word read"). Straight up to 40 over the row (a quarter of the flight), over, straight down (the last quarter);
across on `glide` between a tenth and nine tenths of it. Returns its flight's progress, x and rise, and its ends."""
s = (f - 108 - 18 * k) / 24
sx, ex = BX + 30 * k, FR - 24 - 30 * k
u = clamp01(s)
x = sx + (ex - sx) * glide(clamp01((u - 0.1) / 0.8))
lift = LIFT * min(glide(clamp01(u / 0.25)), glide(clamp01((1 - u) / 0.25)))
return s, x, lift, sx, ex
def walk_row(g, y, state, f=0):
"""The walked row at frame f of the beat: state names the instant (see regroup_strip). Its offsets stand over it,
in the header's row (the walked word is the dump's first); the bytes themselves fly over them, one at a time;
each one's place in the dump takes a faint copy once it has left (from a third of its flight)."""
vals = [D.MEM[WALK + k] for k in range(8)]
faint = mix(VELLUM, PAGE, 0.5)
C.addr(g, 0, y, WALK, STACK if state == "ink" else FAINT)
if state in ("which", "flight", "landed"):
f = {"which": 96, "landed": 258}.get(state, f)
xs = {}
for k, v in enumerate(vals):
s, x, lift, sx, ex = flight(k, f)
xs[k] = (s, x)
if s > 0 and f >= 108 + 8 + 18 * k: # its place keeps a faint copy
g.t(sx, b(y), "%02x" % v, S, faint, MONO)
if 0 < s < 1: # the path, for the still only: up, over, down
pts = [flight(k, 108 + 18 * k + 24 * i / 60)[1:3] for i in range(61)]
seg = [(px + 12, y + ROW / 2 - pl) for px, pl in pts if pl > ROW / 2 + 4] # above the row only
g.path("M" + " L".join("%.1f,%.1f" % q for q in seg), RULE, 2, dash="12 8")
g.rect(x - 3, b(y) - lift - 17, 2 * A + 6, 20, PAGE)
g.t(x, b(y) - lift, "%02x" % v, S, BRIGHT, BOLD)
g.t(x + 12, b(y) - lift - OFF_AIR, "+%d" % k, S, FAINT, MONO, "middle")
else:
g.t(x, b(y), "%02x" % v, S, VELLUM, MONO)
g.t(x + 12, b(y - ROW), "+%d" % k, S, FAINT, MONO, "middle")
# `low byte` left of `+0` at rest, right of it landed (the word's last pair); `high byte` right of `+7` at
# rest, left of it landed; each goes as a byte lifts and comes back as its own lands
s0, x0 = xs[0]
if s0 <= 0 or s0 >= 1:
g.t(x0 - 6 if s0 <= 0 else x0 + 30, b(y - ROW), "low byte", 18, DIM, "sans", "end" if s0 <= 0 else "start")
s6, s7, x7 = xs[6][0], xs[7][0], xs[7][1]
if s6 <= 0 or s7 >= 1:
g.t(x7 + 30 if s6 <= 0 else x7 - 6, b(y - ROW), "high byte", 18, DIM, "sans", "start" if s6 <= 0 else "end")
if state == "closed":
word = "".join("%02x" % vals[k] for k in reversed(range(8)))
g.t(FR, b(y), word, S, VELLUM, MONO, "end")
lead = len(word) - len(word.lstrip("0"))
x0, x1 = FR - 16 * A, FR - (16 - lead) * A
g.path(f"M{x0 + 1},{y + ROW - 8} v6 H{x1 - 1} v-6", FAINT, 2)
g.t(x0, y + ROW + 22, "zeros in front", 18, DIM, "sans")
if state in ("closed", "zeros", "ink"):
for k, v in enumerate(vals):
g.t(BX + 30 * k, b(y), "%02x" % v, S, faint, MONO)
if state in ("zeros", "ink"):
ink = CODE if state == "ink" else VELLUM
g.t(FR, b(y), "10018b0", S, ink, MONO, "end")
if state == "ink":
g.frame(BX - 6, y, 8 * 30, ROW, READ, 2)
g.frame(FR - 7 * A - 6, y, 7 * A + 12, ROW, READ, 2)
def regroup_strip(name):
"""Mock 37: `regroup` walked, on the return address's real bytes, eight instants with their frames (from the
beat's step, motion.md's "A word read"). Each is the frame's x2 camera on the walked row, drawn here at x1.25."""
gen.W, gen.H = 1920, 1520
g = Svg()
cells = [("0 to 48", "eight to a row", "the rows make room; each right half goes down a row, then left", "reflow"),
("66 to 96", "which byte is which", "its offsets over it, in the header's row; the low byte is the first",
"which"),
("174", "in flight, one at a time", "the low byte first, 24 f each, 18 f apart, 40 over the offsets",
"flight"),
("258", "landed, reversed", "the low byte last; each offset lands over its byte", "landed"),
("288", "the spaces close", "sixteen digits, the same eight bytes", "closed"),
("312", "the zeros in front go", "a word is written without them", "zeros"),
("360 to 458", "the other fifteen at a run", "rows 6 f apart: each word fades in (8 f) as its bytes dim",
"run"),
("ink beat", "then its ink, and its mapping", "framed with its band in the address space (mock 30)", "ink")]
for i, (fr, title, sub, state) in enumerate(cells):
ox, oy = 40 + (i % 2) * 950, 30 + (i // 2) * 370
g.t(ox, oy + 26, "%d" % (i + 1), 26, GOLD, "sansb")
g.t(ox + 30, oy + 26, title, 24, VELLUM, "sansm")
g.t(ox + 30 + gen.tw(title, 24, "sansm") + 16, oy + 26, "f " + fr, 20, FAINT, "mono")
g.t(ox + 30, oy + 52, sub, 18, DIM, "sans")
g.o.append(f'<g transform="translate({ox + 10},{oy + 220}) scale(1.25)">')
if state == "reflow": # f 30: the right half on its new row, halfway left
vals = [D.MEM[WALK - 8 + k] for k in range(16)]
C.addr(g, 0, -ROW, WALK - 8, FAINT)
for k in range(8):
g.t(BX + 30 * k, b(-ROW), "%02x" % vals[k], S, VELLUM, MONO)
C.addr(g, 0, 0, WALK, mix(FAINT, PAGE, 0.5)) # f 40: down a row (18 to 30), now halfway left
for k in range(8):
g.t(BX + (30 * 8 + 12) * (1 - glide(10 / 18)) + 30 * k, b(0), "%02x" % vals[8 + k], S, VELLUM, MONO)
elif state == "run":
for r, a in enumerate(range(0x7fffffffed30, 0x7fffffffed50, 8)):
y = (r - 2) * ROW
C.addr(g, 0, y, a, FAINT)
vals = [D.MEM[a + k] for k in range(8)]
fade = [1, 1, 0.5, 0][r] # mid-wave: two rows done, one half in, one to come
for k, v in enumerate(vals):
g.t(BX + 30 * k, b(y), "%02x" % v, S, mix(VELLUM, PAGE, 1 - 0.5 * fade), MONO)
if fade:
g.t(FR, b(y), word_text(D.word(a)), S, mix(VELLUM, PAGE, fade), MONO, "end")
else:
walk_row(g, 0, state, {"which": 96, "flight": 174, "landed": 258}.get(state, 0))
g.o.append("</g>")
g.save(name)
def frame_stack(name):
gen.W, gen.H = 1920, 1080
g = Svg()
camera(g, 1.25, 976 + 440, 212 + 330)
C.RX = 976
C.registers(g, 212, D.regs(False), D.FLAGS, {})
M = __import__("map")
rows = [r for r in M.slot_rows(16, 8)]
frames = M.frames_from(16, 8)
roles = M.roles_from(16, 8)
for _, _, z in frames: # the introduction names the way back too: each frame's last word
if z < len(rows):
roles[z] = ("the way back", DIM)
slot, pins, links, end = rows[z][:4]
v, ink, sym = links[0] # its symbol gives way to the role where both do not fit, as the renderer's
if 184 + 12 * A + 30 + (len("%x" % v) + 1 + len(sym)) * A > C.CW - 136 - len("the way back") * A - 12:
rows[z] = (slot, pins, [(v, ink)], end)
C.HEX0X = True # and writes its offsets with `0x` from 0x10 up
C.stack(g, 664, rows, frames, rsp=RSP, roles=roles)
C.HEX0X = False
g.o.append("</g>")
gen.caption(g, [[("The same words as the stack: rsp points at its top, each word",)],
[("has its offset, a frame is a span, and the registers sit over it.",)]])
g.save(name)
BYTES = {0x1001910: "48 85 ff", 0x1001913: "74 20", 0x1001915: "55", 0x1001916: "48 89 e5", 0x1001919: "31 c0",
0x100191b: "0f 1f 44 00 00", 0x1001920: "48 89 c1", 0x1001923: "48 89 f8", 0x1001926: "48 8b 7f 08",
0x100192a: "48 89 48 08", 0x100192e: "48 85 ff", 0x1001931: "75 ed", 0x1001933: "5d", 0x1001934: "c3",
0x1001935: "31 c0", 0x1001937: "c3"}
def aligned(g, y, first, n, cur, cur_line, bytes_=False, title="reverse"):
"""`aligned`, one panel: the listing interleaved as objdump -S prints it. Each run of a line's instructions
is a group: a head row (the line on raised paper, its number in the place column) and under it its rows,
their addresses in the same column, indented under the line's text. A 2-unit rule over every head: where a
line starts and ends. A line's second run: its head again, faint; rows of no line: a faint head saying so."""
rows = [r for r in D.disasm_rows() if r[0] >= first][:n]
groups, cur_g = [], None
for r in rows:
key = (r[2], r[1]) if r[2] is not None else (None, r[1])
if cur_g is None or cur_g[0] != key:
cur_g = [key, []]
groups.append(cur_g)
cur_g[1].append(r)
total = len(rows) + len(groups)
C.tag(g, 64, y, 1792, ph(total), "list.c · %s" % title, focus=True,
note="each line, then the instructions it compiled to · lines and addresses in one column")
yy, seen = y + TAG + PAD, set()
PLACE, TEXT = 100 + 7 * A, 220 # the place column ends at 196; the text 24 after it
for (line, func), grp in groups:
g.rect(64 + 2, yy, 1792 - 4, 2, RULE) # where a line's group starts (and the last one ends)
again = line in seen
on_line = line == cur_line and any(r[0] == cur for r in grp)
g.rect(64 + 2, yy + 2, 1792 - 4, ROW - 2, RAISED if not again else PAGE)
if line is None:
g.t(TEXT, b(yy), "%s · no line" % func, 18, FAINT, "sans")
else:
if on_line:
g.rect(PLACE - 50 + 12, yy + 2, 50, ROW - 2, GOLD)
g.t(PLACE + 12, b(yy), str(line), S, gen.INK if on_line else (FAINT if again else DIM), BOLD if on_line else MONO,
"end")
text = D.SRC[line - 1].strip()
if again:
g.t(TEXT, b(yy), text + " again: its second run", S, FAINT, MONO)
else:
C.c_line(g, TEXT, yy, text, 80)
seen.add(line)
yy += ROW
for a, f_, ln, mn, ops in grp:
on = a == cur
if on:
g.rect(64 + 2, yy, 1792 - 4, ROW, C.WASH)
g.rect(64 + 2, yy, 24, ROW, GOLD)
g.path(f"M{64 + 20},{yy + 12} l-10,-6 v12 Z", fill=gen.INK)
C.addr(g, PLACE + 12 - len("%x" % a) * A, yy, a, CODE, lead=4)
x = TEXT + 2 * A # indented under the line it came from
if bytes_:
g.t(x, b(yy), BYTES.get(a, ""), S, BRIGHT if on else DIM, MONO)
x += 15 * A
g.t(x, b(yy), mn, S, FAINT if mn == "nop" else KW, MONO if mn == "nop" else BOLD)
C.operands(g, x + 7 * A, yy, mn, ops, VELLUM)
if on:
C.chain(g, 64 + 900, yy, [(0x1004098, HEAP), (0x1004070, HEAP)], ("int", 9), None, room=64 + 1780)
yy += ROW
g.rect(64 + 2, yy, 1792 - 4, 2, RULE)
return yy
def columns(g, y, first, n, cur, cur_line, title="reverse"):
"""`aligned` `columns`: one panel, two columns: the source on the left, its instructions on the right, the seam
the frame's gutter. A group is a run of a line's instructions; the line stands level with the run's first row,
its cell as tall as the run, its first row on raised paper; a 2-unit rule over each group across both columns.
Each column's place (the line's number, the instruction's address) ranged right in the same slot at its
column's start, in the same face. A line's second run: the line again, faint, `again`. Rows of no line: the
cell empty but for the function's name, faint. Lines with no code of their own: in source order after the
line before them, faint, their instruction cell empty."""
rows = [r for r in D.disasm_rows() if r[0] >= first][:n]
groups = [] # (lines, rows): lines (number or None, func); rows in order
for r in rows:
key = (r[2], r[1]) if r[2] is not None else (None, r[1])
if not groups or groups[-1][0] != [key]:
groups.append([[key], []])
groups[-1][1].append(r)
out, seen = [], set() # the lines with no code, after the line before them
for (key,), rs in groups:
out.append(([key], rs))
line = key[0]
if line is not None and line not in seen:
seen.add(line)
nxt = line + 1
gap = []
while nxt not in {r[2] for r in D.disasm_rows() if r[1] == key[1]} and nxt < 40 and \
D.SRC[nxt - 1].strip() and nxt not in seen and any(r[2] and r[2] > nxt for r in rows):
gap.append((nxt, key[1]))
nxt += 1
if gap and gap[0][0] not in seen:
seen.update(l for l, _ in gap)
out.append((gap, []))
total = sum(max(len(ls), len(rs)) for ls, rs in out)
C.tag(g, 64, y, 1792, ph(total), "list.c · %s" % title, focus=True,
note="each line level with its instructions")
PL = 132 # a place is ranged right 132 into its column: seven digits
longest = max(len(D.SRC[l - 1].strip()) for ls, _ in out for l, _ in ls if l)
LX, RX = 64, 64 + PL + 24 + (longest + 4) * A # the seam: the longest line and 48 after it
g.rect(RX - 1, y + TAG, 2, ph(total) - TAG - 2, RULE)
yy, done = y + TAG + PAD, set()
for lines, rs in out:
h = max(len(lines), len(rs))
g.rect(66, yy, 1788, 2, RULE) # where a group starts (and the last one ends)
for i, (line, func) in enumerate(lines):
ly = yy + i * ROW
nocode = not rs
again = line in done and not nocode
if line is None:
g.t(LX + PL + 24, b(ly), "%s · no line" % func, 18, FAINT, "sans")
continue
on = line == cur_line and any(r[0] == cur for r in rs)
if i == 0 and not again and not nocode: # the line's row: raised, as a head; the wash if it is current
g.rect(LX + 2, ly + 2, RX - 1 - LX - 2, ROW - 2, C.WASH if on else RAISED)
if on:
g.rect(LX + PL - 50, ly + 2, 50, ROW - 2, GOLD)
g.t(LX + PL, b(ly), str(line), S, gen.INK if on else (FAINT if again or nocode else DIM),
BOLD if on else MONO, "end")
text = D.SRC[line - 1].strip()
if again:
g.t(LX + PL + 24, b(ly), text, S, FAINT, MONO)
g.t(LX + PL + 24 + (len(text) + 3) * A, b(ly), "again: its second run", 18, FAINT, "sans")
elif nocode:
g.t(LX + PL + 24, b(ly), text, S, FAINT, MONO)
else:
C.c_line(g, LX + PL + 24, ly, text, 56)
done.add(line)
if not rs:
g.t(RX + PL + 24, b(yy), "no code of their own", 18, FAINT, "sans")
for j, (a, f_, ln, mn, ops) in enumerate(rs):
ry = yy + j * ROW
if a == cur:
g.rect(RX + 1, ry, 1854 - RX - 1, ROW, C.WASH)
g.rect(RX + 1, ry, 24, ROW, GOLD)
g.path(f"M{RX + 19},{ry + 12} l-10,-6 v12 Z", fill=gen.INK)
C.addr(g, RX + PL - len("%x" % a) * A, ry, a, CODE, lead=4)
x = RX + PL + 24
g.t(x, b(ry), mn, S, FAINT if mn in ("nop", "endbr64") else KW, MONO if mn in ("nop", "endbr64") else BOLD)
C.operands(g, x + 7 * A, ry, mn, ops, VELLUM)
if a == cur:
C.chain(g, RX + PL + 24 + 30 * A, ry, [(0x1004098, HEAP), (0x1004070, HEAP)], ("int", 9), None, room=1844)
yy += h * ROW
g.rect(66, yy, 1788, 2, RULE)
return yy
def frame_columns(name):
"""Mock 36: `aligned` `columns` on mock 33's data: reverse, the pc at the load, and _init after it."""
gen.W, gen.H = 1920, 1080
g = Svg()
columns(g, 48, 0x1001910, 18, 0x1001926, 21)
gen.caption(g, [[("The same listing in two columns: each line level with the first",)],
[("of its instructions. Lines 23 to 25 compiled to nothing of their own.",)]])
g.save(name)
def frame_code(name):
"""The code chapter: the source and its instructions side by side, each line level with its code, and the
instruction's bytes between the address and the mnemonic: an instruction is bytes too."""
gen.W, gen.H = 1920, 1080
g = Svg()
aligned(g, 48, 0x1001910, 16, 0x1001926, 21, bytes_=True)
gen.caption(g, [[("48 8b 7f 08", "mono"), (" is one instruction: ",), ("mov rdi, [rdi + 8]", "mono"), (", line 21's",)],
[("head->next", "mono"), (". The line sits level with its code: they are one row.",)]])
g.save(name)
def frame_aligned(name):
"""Mock 33: the `aligned` split, reverse and list_done, the pc at the load."""
gen.W, gen.H = 1920, 1080
g = Svg()
aligned(g, 48, 0x1001910, 16, 0x1001926, 21)
gen.caption(g, [[("Line 20, ",), ("while (head)", "mono"), (", comes twice: its test before the body and",)],
[("again after it. Lines 23 to 25 have no code of their own: no group.",)]])
g.save(name)
if __name__ == "__main__":
frame_bytes("29-intro-bytes")
frame_words("30-intro-words")
frame_stack("31-intro-stack")
frame_code("32-intro-code")
frame_aligned("33-aligned")
frame_space("34-segments")
sheet_abc("35-segments-abc")
frame_columns("36-aligned-columns")
regroup_strip("37-regroup")
|