From 2311d3617ee17a89b647fea722c47ec739fd63f3 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Thu, 12 Nov 2026 07:03:05 -0300 Subject: design: the introduction's storyboard as built The storyboard and catalogue follow what the introduction became after its review: the plain build, chapter II's six beats with the stack's convention said and the call before the push, the regroup's bytes flying one at a time over their row, the dump folding into its tag, the Eiffel visit at x2 with the 128 bytes marked, hex offsets, names only after the things. The aim's head is 10; a beat's link fades its head as it draws back. Mocks 29, 30, 31 and 37 redrawn. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- design/mock/29-intro-bytes.png | Bin 83086 -> 78336 bytes design/mock/29-intro-bytes.svg | 6 +- design/mock/30-intro-words-480.png | Bin 21208 -> 21282 bytes design/mock/30-intro-words.png | Bin 128243 -> 128806 bytes design/mock/30-intro-words.svg | 4 +- design/mock/31-intro-stack.png | Bin 144165 -> 148516 bytes design/mock/31-intro-stack.svg | 15 ++-- design/mock/37-regroup.png | Bin 138314 -> 125817 bytes design/mock/37-regroup.svg | 112 +++++++++++++------------- design/mock/context.py | 6 +- design/mock/intro.py | 159 ++++++++++++++++++++----------------- 11 files changed, 157 insertions(+), 145 deletions(-) (limited to 'design/mock') diff --git a/design/mock/29-intro-bytes.png b/design/mock/29-intro-bytes.png index e382abe..3d6c1a9 100644 Binary files a/design/mock/29-intro-bytes.png and b/design/mock/29-intro-bytes.png differ diff --git a/design/mock/29-intro-bytes.svg b/design/mock/29-intro-bytes.svg index fcd07cc..e9fad54 100644 --- a/design/mock/29-intro-bytes.svg +++ b/design/mock/29-intro-bytes.svg @@ -2,7 +2,7 @@ -128 bytes, from where rsp points +128 bytes at 7fffffffece0 7fffffffece0 00 ed @@ -140,6 +140,6 @@ 00 00 -A running program is bytes in memory. -These are 128 of them, sixteen to a row. +A running program is bytes in memory: +here are 128 of them. diff --git a/design/mock/30-intro-words-480.png b/design/mock/30-intro-words-480.png index 4f4c1b4..c1768f9 100644 Binary files a/design/mock/30-intro-words-480.png and b/design/mock/30-intro-words-480.png differ diff --git a/design/mock/30-intro-words.png b/design/mock/30-intro-words.png index d4a29db..1abc71b 100644 Binary files a/design/mock/30-intro-words.png and b/design/mock/30-intro-words.png differ diff --git a/design/mock/30-intro-words.svg b/design/mock/30-intro-words.svg index 37708fc..63b0416 100644 --- a/design/mock/30-intro-words.svg +++ b/design/mock/30-intro-words.svg @@ -190,7 +190,7 @@ 00 00 00 -1f7fbe000 +0x1f7fbe000 7fffffffed28 60 18 @@ -240,7 +240,7 @@ 35 e3 1f -1fe335fc95a5781c +0x1fe335fc95a5781c 7fffffffed50 38 ee diff --git a/design/mock/31-intro-stack.png b/design/mock/31-intro-stack.png index a85abd2..69ea78c 100644 Binary files a/design/mock/31-intro-stack.png and b/design/mock/31-intro-stack.png differ diff --git a/design/mock/31-intro-stack.svg b/design/mock/31-intro-stack.svg index e3eadcd..7eb286a 100644 --- a/design/mock/31-intro-stack.svg +++ b/design/mock/31-intro-stack.svg @@ -133,26 +133,27 @@ +8 +the way back 7fffffffe ce8 10018b0 main+80 -+10 ++0x10 7fffffffe cf0 7ffff7e20de8 -+18 ++0x18 saved rbx 7fffffffe cf8 0 -+20 ++0x20 saved rbp 7fffffffe d00 @@ -164,21 +165,21 @@ -+28 ++0x28 +the way back 7fffffffe d08 7ffff7c27781 -libc+27781 -+30 ++0x30 7fffffffe d10 7ffff7fe0c60 ld.so+22c60 -+38 ++0x38 7fffffffe d18 diff --git a/design/mock/37-regroup.png b/design/mock/37-regroup.png index b984d76..b1a23a1 100644 Binary files a/design/mock/37-regroup.png and b/design/mock/37-regroup.png differ diff --git a/design/mock/37-regroup.svg b/design/mock/37-regroup.svg index d500058..0737821 100644 --- a/design/mock/37-regroup.svg +++ b/design/mock/37-regroup.svg @@ -28,98 +28,101 @@ 2 which byte is which f 66 to 96 -its offsets under it; the low byte is the first in memory +its offsets over it, in the header's row; the low byte is the first 7fffffffece8 b0 ++0 18 ++1 00 ++2 01 ++3 00 ++4 00 ++5 00 ++6 00 -+0 -+1 -+2 -+3 -+4 -+5 -+6 -+7 -low byte -high byte ++7 +low byte +high byte 3 -in flight, the low byte first -f 138 -6 f apart, 36 f each, on nested arcs; a faint copy stays +in flight, one at a time +f 174 +the low byte first, 24 f each, 18 f apart, 40 over the offsets 7fffffffece8 b0 +b0 ++0 18 +18 ++1 00 +00 ++2 01 + + +01 ++3 +00 ++4 00 ++5 00 ++6 00 -+5 -+6 -+7 -high byte - -b0 - - -18 - - -00 - - -01 - -00 ++7 +low byte +high byte 4 landed, reversed -f 186 -the low byte last; each offset lands under its byte +f 258 +the low byte last; each offset lands over its byte 7fffffffece8 b0 -18 -00 -01 -00 -00 -00 -00 b0 -+0 ++0 +18 18 -+1 ++1 +00 00 -+2 ++2 +01 01 -+3 ++3 +00 00 -+4 ++4 +00 00 -+5 ++5 +00 00 -+6 ++6 +00 00 -+7 -low byte -high byte ++7 +low byte +high byte 5 the spaces close -f 216 +f 288 sixteen digits, the same eight bytes 7fffffffece8 +00000000010018b0 + +zeros in front b0 18 00 @@ -128,13 +131,10 @@ 00 00 00 -00000000010018b0 - -zeros in front 6 the zeros in front go -f 240 +f 312 a word is written without them 7fffffffece8 @@ -150,7 +150,7 @@ 7 the other fifteen at a run -f 288 to 386 +f 360 to 458 rows 6 f apart: each word fades in (8 f) as its bytes dim 7fffffffed30 diff --git a/design/mock/context.py b/design/mock/context.py index 5549d02..2e8b450 100644 --- a/design/mock/context.py +++ b/design/mock/context.py @@ -99,6 +99,7 @@ def held_cell(g, x, y, w, h, k=1): MINIMAP = 0 # a pane with its own minimap: the frame this much wider than its content +HEX0X = False # the introduction's offsets: `0x` from 0x10 up (`-8`, `+0x10`) def tag(g, x, y, w, h, title, focus=False, note=None): @@ -407,9 +408,10 @@ def stack(g, y, rows, frames, note=None, rsp=None, roles=None, touched=(), chain ys.append(yy) if pins: pin(g, RX + 16, yy, pins, STACK) - if rsp is not None: # the offset from rsp, pwndbg's way: +18 + if rsp is not None: # the offset from rsp, pwndbg's way: +18 (the introduction's +0x18) off = slot - rsp - g.t(RX + 172, b(yy), ("+%x" % off) if off >= 0 else ("-%x" % -off), S, FAINT, MONO, "end") + p = "0x" if HEX0X and abs(off) >= 0x10 else "" + g.t(RX + 172, b(yy), ("+%s%x" % (p, off)) if off >= 0 else ("-%s%x" % (p, -off)), S, FAINT, MONO, "end") end_x = room.get(i, RX + CW - 136) if marks and marks[0].get("free"): # above rsp: not the stack's yet; its word faint, no chain g.t(first, b(yy), "%x" % slot, S, mix(STACK, PAGE, 0.6), MONO) diff --git a/design/mock/intro.py b/design/mock/intro.py index 87d22bf..a35ddb3 100644 --- a/design/mock/intro.py +++ b/design/mock/intro.py @@ -290,6 +290,12 @@ def camera(g, k, cx, cy): g.o.append(f'') +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.""" @@ -306,7 +312,7 @@ def raw_dump(g, x, y, rows, per=16, words=False, inked=False): 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), "%x" % w_, S, ink, MONO, "end") + g.t(bx + per * 30 + 24 + 8 * 30, b(yy), word_text(w_), S, ink, MONO, "end") return ys @@ -315,11 +321,11 @@ def frame_bytes(name): gen.W, gen.H = 1920, 1080 g = Svg() g.o.append('') - g.t(0, -10, "128 bytes, from where rsp points", 18, FAINT, "sans") + 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("") - gen.caption(g, [[("A running program is bytes in memory.",)], - [("These are 128 of them, sixteen to a row.",)]]) + gen.caption(g, [[("A running program is bytes in memory:",)], + [("here are 128 of them.",)]]) g.save(name) @@ -370,78 +376,68 @@ def glide(t): return 3 * (1 - m) * m * m + m ** 3 -def flight(k, t, closed=False): - """Where byte k is at t of its flight: straight up off its place, over on an arc a quarter as high as it is long - (34 to 120), straight down onto its pair's place in the word, the pairs 30 apart as they land. Returns the - byte's x and rise, its two ends and the arc's height; arc(k, u) is the path.""" - sx = BX + 30 * k - ex = FR - (24 if closed else 30) * (k + 1) + (0 if closed else 6) - h = min(max((ex - sx) / 4, 34), 120) - x, y = arc(sx, ex, h, glide(t)) - return x, y, sx, ex, h +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 arc(sx, ex, h, u): - """The cubic from (sx, 0) to (ex, 0) leaving and arriving upright, h high at its middle.""" - H = h / 0.75 - return sx + (ex - sx) * (3 * u * u - 2 * u ** 3), -3 * (1 - u) * u * H + +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). The bytes themselves - fly; each one's place in the dump takes a faint copy once it has left (from a third of its flight).""" + """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) - t_ = lambda k: (f - 108 - 6 * k) / 36 if state == "flight" else (1 if state != "which" else 0) - for k, v in enumerate(vals): - t = t_(k) - if t <= 0: - g.t(BX + 30 * k, b(y), "%02x" % v, S, VELLUM, MONO) - elif t >= 1 / 3: - g.t(BX + 30 * k, b(y), "%02x" % v, S, faint, MONO) - if state in ("which", "flight"): - for k in range(8): # the offsets: where each byte is, under it - if t_(k) <= 0: - g.t(BX + 30 * k + 12, b(y + ROW), "+%d" % k, S, FAINT, MONO, "middle") - if t_(0) <= 0: - g.t(BX + 12, y + 2 * ROW + 16, "low byte", 18, DIM, "sans", "middle") - if t_(7) <= 0: - g.t(BX + 7 * 30 + 12, y + 2 * ROW + 16, "high byte", 18, DIM, "sans", "middle") - if state == "flight": - for k in range(8): - t = t_(k) - x, yy, sx, ex, h = flight(k, min(max(t, 0), 1)) - if 0 < t < 1: # the path, for the still only, broken round the byte - pts = [(arc(sx, ex, h, u)[0] + 12, y + ROW / 2 + arc(sx, ex, h, u)[1]) for u in [i / 60 for i in range(61)]] - seg = [] - for p in pts + [None]: - if p is not None and p[1] < y - 4 and (abs(p[0] - x - 12) > 26 or abs(p[1] - (y + yy + ROW / 2)) > 16): - seg.append(p) - continue - if len(seg) > 1: - g.path("M" + " L".join("%.1f,%.1f" % q for q in seg), RULE, 2, dash="12 8") - seg = [] - g.t(x, b(y + yy), "%02x" % vals[k], S, BRIGHT, BOLD) - if t >= 1: - g.t(ex, b(y), "%02x" % vals[k], S, VELLUM, MONO) - g.t(ex + 12, b(y + ROW), "+%d" % k, S, FAINT, MONO, "middle") - if t_(0) >= 1: - g.t(FR - 12, y + 2 * ROW + 16, "low byte", 18, DIM, "sans", "middle") - if state == "landed": - for k in range(8): - ex = FR - 30 * (k + 1) + 6 - g.t(ex, b(y), "%02x" % vals[k], S, VELLUM, MONO) - g.t(ex + 12, b(y + ROW), "+%d" % k, S, FAINT, MONO, "middle") - g.t(FR - 12, y + 2 * ROW + 16, "low byte", 18, DIM, "sans", "middle") - g.t(FR - 234 + 12, y + 2 * ROW + 16, "high byte", 18, DIM, "sans", "middle") + 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 + 2} v6 H{x1 - 1} v-6", FAINT, 2) - g.t((x0 + x1) / 2, y + ROW + 30, "zeros in front", 18, DIM, "sans", "middle") + 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") @@ -451,18 +447,19 @@ def walk_row(g, y, state, f=0): def regroup_strip(name): - """Mock 37: `regroup` walked, on the return address's real bytes, seven instants with their frames (from the - beat's step, 552 in the introduction's chart). Each is the frame's x2 camera on the dump, drawn here at x1.5.""" + """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 under it; the low byte is the first in memory", "which"), - ("138", "in flight, the low byte first", "6 f apart, 36 f each, on nested arcs; a faint copy stays", + ("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"), - ("186", "landed, reversed", "the low byte last; each offset lands under its byte", "landed"), - ("216", "the spaces close", "sixteen digits, the same eight bytes", "closed"), - ("240", "the zeros in front go", "a word is written without them", "zeros"), - ("288 to 386", "the other fifteen at a run", "rows 6 f apart: each word fades in (8 f) as its bytes dim", + ("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): @@ -489,9 +486,9 @@ def regroup_strip(name): 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), "%x" % D.word(a), S, mix(VELLUM, PAGE, fade), MONO, "end") + 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": 138}.get(state, 0)) + walk_row(g, 0, state, {"which": 96, "flight": 174, "landed": 258}.get(state, 0)) g.o.append("") g.save(name) @@ -502,8 +499,20 @@ def frame_stack(name): 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)) + 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("") 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.",)]]) -- cgit v1.3