diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-11 11:27:09 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-11 11:51:02 -0300 |
| commit | beb2616a243e01826c3103209d5525381a5da73d (patch) | |
| tree | 195c30132791de8ed1bed0461ce2825bdfbfe819 /design/mock/intro.py | |
| parent | dcbe8941df205fa8c8805b022f025e1012dede19 (diff) | |
| download | computeranim-beb2616a243e01826c3103209d5525381a5da73d.tar.gz computeranim-beb2616a243e01826c3103209d5525381a5da73d.zip | |
design: an introduction that builds the views; segments; source and disassembly aligned
From the user. Three short chapters teach the frame by assembling it:
bytes become words, words that are addresses take the ink of the mapping
they point into, the stack's conventions are shown on those same rows by
a real push and call, an instruction's bytes decode into its row beside
its source line, and the working frame stands at the end. segments is the
process's mappings as rows, the legend's long form. aligned is a split a
scene chooses: each source line level with the first row of its
instructions. Verbs for building a view: regroup, ink, column, frame up,
decode, align.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'design/mock/intro.py')
| -rw-r--r-- | design/mock/intro.py | 217 |
1 files changed, 217 insertions, 0 deletions
diff --git a/design/mock/intro.py b/design/mock/intro.py new file mode 100644 index 0000000..b9c7d7d --- /dev/null +++ b/design/mock/intro.py @@ -0,0 +1,217 @@ +#!/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 (("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 segments(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 + + +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) + segments(g, 12 * A + 12 + 8 * 30 + 24 + 13 * A + 36, -24, 560, hot={0x1001000}) + 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`: the source and the disassembly side by side, a table in address order: each source line level + with the first row of its run of instructions, a line that comes again (a second run) repeated faint at that + run, a line with no code of its own not drawn (its number missing says so), a row of no line (padding) with + nothing beside it. The pc's row and its line are one band across both columns: the alignment is the thread.""" + rows = [r for r in D.disasm_rows() if r[0] >= first][:n] + h = ph(n) + C.tag(g, 64, y, 880, h, "list.c", note="each line beside the first of its instructions") + C.tag(g, 976, y, 880, h, "disassembly", note=title) + y0 = y + TAG + PAD + seen, last_line = set(), None + lead = C.shared([r[0] for r in rows]) + i0 = 0 # each run's extent: a quiet bracket by the gutter, line to its last row + for i in range(1, n + 1): + if i == n or rows[i][2] != rows[i0][2]: + if rows[i0][2] is not None: + C.bracket(g, 932, y + TAG + PAD + i0 * ROW + 3, y + TAG + PAD + i * ROW - 3, RULE, 2, 5, side=-1) + i0 = i + for i, (a, func, line, mn, ops) in enumerate(rows): + yy = y0 + i * ROW + on = a == cur + if on: # one band through the gutter: the line and its instruction are one + g.rect(64 + 2, yy, 880 - 4, ROW, C.WASH) + g.rect(944, yy, 32, ROW, C.WASH) + g.rect(976 + 2, yy, 880 - 4, ROW, C.WASH) + g.rect(976 + 2, yy, 24, ROW, GOLD) + g.path(f"M{976 + 20},{yy + 12} l-10,-6 v12 Z", fill=gen.INK) + if line is not None and line != last_line: + again = line in seen + if line == cur_line and on: + g.rect(64 + 2, yy, 50, ROW, GOLD) + g.t(64 + 46, b(yy), str(line), S, gen.INK, BOLD, "end") + else: + g.t(64 + 46, b(yy), str(line), S, FAINT, MONO, "end") + text = D.SRC[line - 1] + C.c_line(g, 64 + 64, yy, text, 66) if not again else g.t(64 + 64, b(yy), text.strip(), S, FAINT, MONO) + seen.add(line) + elif line is None and (i == 0 or rows[i - 1][1] != func): + g.t(64 + 64, b(yy), "%s · no line" % func, 18, FAINT, "sans") + last_line = line + C.addr(g, 976 + 40, yy, a, CODE, lead=lead) + x = 976 + 40 + 8 * A + 12 + 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, 976 + 600, yy, [(0x1004098, HEAP), (0x1004070, HEAP)], ("int", 9), {0: "read"} if False else None, + room=976 + 868) + return y0 + + +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, 30, 0x1001926, 21) + gen.caption(g, [[("Line 20, ",), ("while (head)", "mono"), (", has two runs: its test before the body",)], + [("and again after it. Lines 23 to 25 have no code of their own.",)]]) + 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") |
