summaryrefslogtreecommitdiff
path: root/design/mock/intro.py
blob: 098455cbec864ce30739958f3482952984b821c2 (plain) (blame)
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
#!/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). Four
instants of the build, each as the camera frames it.

    python3 -B intro.py     # 29-intro-bytes, 30-intro-words, 31-intro-stack, 32-intro-code (.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
MAPS = [(0x1000000, 0x1001000, "list", "headers, read-only", VELLUM), (0x1001000, 0x1002000, "list", "code", CODE),
        (0x1002000, 0x1003000, "list", "read-only data", VELLUM), (0x1003000, 0x1004000, "list", "data", DATA),
        (0x1004000, 0x1025000, "heap", "malloc's", HEAP), None,
        (0x7ffff7c00000, 0x7ffff7c24000, "libc.so.6", "read-only", VELLUM),
        (0x7ffff7c24000, 0x7ffff7d9f000, "libc.so.6", "code", CODE),
        (0x7ffff7d9f000, 0x7ffff7e15000, "libc.so.6", "read-only data", VELLUM),
        (0x7ffff7e15000, 0x7ffff7e23000, "libc.so.6", "data", DATA), (0x7ffff7fbc000, 0x7ffff7fbe000, "[vdso]", "code", CODE),
        (0x7ffff7fbf000, 0x7ffff7fec000, "ld.so", "code", CODE), (0x7ffff7ffb000, 0x7ffff7fff000, "ld.so", "data", DATA),
        None, (0x7ffffffde000, 0x7ffffffff000, "[stack]", "the stack", STACK)]
CODE_BYTES = [(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")]


def size(n):
    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" if v == int(v) or v >= 10 else "%.1f %s") % (v, unit)
    return "%d B" % n


def segment_rows(g, x, y, w, hot=()):
    """`segments`: the process's address space as its mappings, low addresses on top, a row each: a bar in the
    region's ink, the first address, what it is, its size; a hole between them one row, how big it is. Rows, not
    a scale: the stack and the code are 127 TiB apart. hot: the mappings framed as read (a word just inked)."""
    rows = len(MAPS)
    y0 = C.panel(g, x, y, w, rows, "the address space", note="the recording's mappings, low on top")
    last = None
    for i, m in enumerate(MAPS):
        yy = y0 + i * ROW
        if m is None:                    # a hole: what is not mapped
            nxt = next(mm for mm in MAPS[i + 1:] if mm)
            hole = nxt[0] - last
            g.path(f"M{x + 14},{yy + 8} l6,4 l-6,4 l6,4", FAINT, 2)
            g.t(x + 40, b(yy), "nothing mapped · %s" % size(hole), 18, FAINT, "sans")
            continue
        lo, hi, name, what, ink = m
        g.rect(x + 12, yy + 3, 8, ROW - 6, ink)
        C.addr(g, x + 32, yy, lo, ink)
        g.t(x + 32 + 13 * A, b(yy), name, S, VELLUM, MONO)
        g.t(x + 32 + 13 * A + 11 * A, b(yy), what, 18, DIM, "sans")
        g.t(x + w - 12, b(yy), size(hi - lo), S, FAINT, MONO, "end")
        if lo in hot:
            g.frame(x + 6, yy, w - 12, ROW, READ, 2)
        last = hi
    return y0


# the mappings at the stop, as `ztrace show` prints them (range, permissions, file offset, file); high on top
MAPPINGS = [(0xffffffffff600000, 0xffffffffff601000, "--x", "[vsyscall]"),
            (0x7ffffffde000, 0x7ffffffff000, "rw-", "[stack]"),
            (0x7ffff7ffe000, 0x7ffff7fff000, "rw-", ""), (0x7ffff7ffd000, 0x7ffff7ffe000, "rw-", "ld.so"),
            (0x7ffff7ffb000, 0x7ffff7ffd000, "r--", "ld.so"), (0x7ffff7fec000, 0x7ffff7ffb000, "r--", "ld.so"),
            (0x7ffff7fbf000, 0x7ffff7fec000, "r-x", "ld.so"), (0x7ffff7fbe000, 0x7ffff7fbf000, "r--", "ld.so"),
            (0x7ffff7fbc000, 0x7ffff7fbe000, "r-x", "[vdso]"), (0x7ffff7fb6000, 0x7ffff7fbc000, "r--", "[vvar]"),
            (0x7ffff7f75000, 0x7ffff7fb6000, "r--", "ld.so.cache"), (0x7ffff7f70000, 0x7ffff7f75000, "rw-", ""),
            (0x7ffff7e1b000, 0x7ffff7e23000, "rw-", ""), (0x7ffff7e19000, 0x7ffff7e1b000, "rw-", "libc.so.6"),
            (0x7ffff7e15000, 0x7ffff7e19000, "r--", "libc.so.6"), (0x7ffff7d9f000, 0x7ffff7e15000, "r--", "libc.so.6"),
            (0x7ffff7c24000, 0x7ffff7d9f000, "r-x", "libc.so.6"), (0x7ffff7c00000, 0x7ffff7c24000, "r--", "libc.so.6"),
            (0x1004000, 0x1025000, "rw-", "[heap]"), (0x1003000, 0x1004000, "rw-", "list"),
            (0x1002000, 0x1003000, "r--", "list"), (0x1001000, 0x1002000, "r-x", "list"), (0x1000000, 0x1001000, "r--", "list")]
INK = {"r-x": CODE, "--x": CODE, "r--": VELLUM, "rw-": DATA}
WHAT = {"r-x": "code", "--x": "code", "r--": "read-only", "rw-": "data"}


def band_h(n):
    """A band's height: 24 at least (a label's row), and 4 a doubling past 4 KiB: schematic, not to scale."""
    import math
    return 24 + 4 * max(math.log2(n / 4096), 0)


def segments(g, x, y, hot=(), rsp=None, rip=None, label_x=None):
    """`segments`: the address space as one tall rectangle, high addresses on top, as the textbook draws it.
    Bands in their mapping's ink (55% toward the page), a file's mappings touching, its parts split by a page
    line; a hole a fixed 40 with a break and its size. Labels beside with leaders: the left the band's first
    address, the right its permissions, what it is, its size; a file's parts bracketed with the file's name.
    Live: rsp's and rip's pins at their place; a band framed when a word is inked into it; growth arrows."""
    W = 140
    lx = label_x or x + W + 40
    yy, last_lo, groups, pos = y, None, [], {}
    g.t(x - 12, yy - 6, "ffffffffffffffff", 18, FAINT, "sans", "end")
    for lo, hi, perm, name in MAPPINGS:
        if last_lo is not None and hi < last_lo:             # a hole: compressed to 40, a break and its size
            gap = last_lo - hi
            g.rect(x, yy, W, 40, PAGE)
            g.frame(x, yy - 1, W, 42, RULE, 2)
            for dy in (14, 24):
                g.path(" ".join(["M%d,%d" % (x - 6, yy + dy)] + ["l%d,%d" % (10, -6 if k % 2 == 0 else 6)
                                                                 for k in range(16)]), RULE, 2)
            for kk, (unit, k) in enumerate((("TiB", 1 << 40), ("GiB", 1 << 30), ("MiB", 1 << 20), ("KiB", 1 << 10))):
                if gap >= k:
                    g.t(lx, yy + 26, "nothing mapped · %s" % size(gap), 18, FAINT, "sans")
                    break
            yy += 40
        h = band_h(hi - lo)
        ink = INK[perm] if name not in ("[stack]", "[heap]") else (STACK if name == "[stack]" else HEAP)
        g.rect(x, yy, W, h, mix(ink, PAGE, 0.55))
        g.rect(x, yy, W, 2, PAGE)                            # a mapping's edge
        mid = yy + h / 2
        g.path(f"M{x + W + 4},{mid} H{lx - 8}", RULE, 2)      # the leader
        g.t(lx, mid + 7, perm, S, ink if perm != "r--" else VELLUM, MONO)
        g.t(lx + 4 * A, mid + 7, (name if name.startswith("[") else WHAT[perm]) + ("" if name else " (anonymous)"),
            18, DIM, "sans")
        g.t(lx + 4 * A + 170, mid + 7, size(hi - lo), S, FAINT, MONO)
        C.addr(g, x - 12 - len("%x" % lo) * A, yy + h - ROW, lo, ink)
        if lo in hot:
            g.frame(x - 4, yy - 2, W + 8, h + 4, READ, 3)
        pos[name, lo] = (yy, h)
        if name and not name.startswith("[") and (not groups or groups[-1][0] != name):
            groups.append([name, yy, yy + h])
        elif name and groups and groups[-1][0] == name:
            groups[-1][2] = yy + h
        yy += h
        last_lo = lo
    for name, a, z in groups:                                # a file's mappings: one thing, with parts
        C.bracket(g, lx + 4 * A + 280, a + 3, z - 3, DIM, 2, 6, side=-1)
        g.t(lx + 4 * A + 292, (a + z) / 2 + 7, name, S, VELLUM, MONO)
    g.t(x - 12, yy + 18, "0", 18, FAINT, "sans", "end")
    # growth: the stack down from its top, the heap up from its base
    sy, sh = pos["[stack]", 0x7ffffffde000]
    gen.arrow(g, [(x + W - 24, sy + 8), (x + W - 24, sy + sh - 6)], BRIGHT, 2, hl=8, hw=8)
    hy, hh = pos["[heap]", 0x1004000]
    gen.arrow(g, [(x + W - 24, hy + hh - 6), (x + W - 24, hy + 8)], BRIGHT, 2, hl=8, hw=8)
    if rsp:                                                  # a register's pin at its place in its band
        f = (0x7ffffffff000 - rsp) / (0x7ffffffff000 - 0x7ffffffde000)
        py = sy + f * sh
        g.t(x + 8, py + 7, "rsp", S, VELLUM, BOLD)
        g.path(f"M{x + 48},{py} l9,-6 v12 Z", fill=STACK)
    if rip:
        cy, ch = pos["list", 0x1001000]
        g.t(x + 8, cy + ch / 2 + 7, "rip", S, VELLUM, BOLD)
        g.path(f"M{x + 48},{cy + ch / 2} l9,-6 v12 Z", fill=CODE)
    g.t(x, y - 34, "the address space", 20, VELLUM, "sansm")
    g.t(x + 200, y - 34, "high addresses on top · not to scale: holes 40, bands by the log of their size", 18,
        FAINT, "sans")
    return yy


def frame_space(name):
    """Mock 34: the rectangle alone, every label reading."""
    gen.W, gen.H = 1920, 1080
    g = Svg()
    segments(g, 560, 110, rsp=RSP, rip=0x1001926, label_x=760)
    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 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:
            w_ = D.word(a0)
            ink = (D.region(w_) or VELLUM) if inked else VELLUM
            g.t(bx + per * 30 + 24, b(yy), "%x" % w_ if w_ else "0", S, ink, MONO)
    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, from where rsp points", 18, FAINT, "sans")
    raw_dump(g, 0, 0, 8)
    g.o.append("</g>")
    gen.caption(g, [[("A running program is bytes in memory.",)],
                     [("These are 128 of them, sixteen to a row.",)]])
    g.save(name)


def frame_words(name):
    """Eight bytes a row now, each row's word beside it, inked by where it points; the address space beside."""
    gen.W, gen.H = 1920, 1080
    g = Svg()
    g.o.append('<g transform="translate(64,96) scale(1.35)">')
    g.t(0, -10, "eight bytes a row, read right to left, a word", 18, FAINT, "sans")
    ys = raw_dump(g, 0, 0, 16, per=8, words=True, inked=True)
    k = 1                                 # 7fffffffece8: the return address, main+80
    g.frame(12 * A + 12 - 4, ys[k] - 1, 8 * 30 + 4, ROW + 2, READ, 2)
    g.frame(12 * A + 12 + 8 * 30 + 24 - 6, ys[k] - 1, 7 * A + 12, ROW + 2, READ, 2)
    g.o.append("</g>")
    g.o.append('<g transform="translate(0,0)">')
    g.o.append('<g transform="translate(1000,110) scale(0.8)">')       # the stage holds it whole above the caption
    segments(g, 200, 0, hot={0x1001000}, rsp=RSP, label_x=380)
    g.o.append("</g>")
    g.o.append("</g>")
    gen.caption(g, [[("Eight bytes make a word, stored low byte first: read right to left,",)],
                     [("this one is ",), ("10018b0", "mono"), (", an address in the code, so it takes code's ink.",)]])
    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, {})
    rows = [r for r in __import__("map").slot_rows(16, 8)]
    C.stack(g, 664, rows, __import__("map").frames_from(16, 8), rsp=RSP, roles=__import__("map").roles_from(16, 8))
    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 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")