summaryrefslogtreecommitdiff
path: root/design/mock/context.py
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 15:17:21 -0300
committerGabriel Schneider <[email protected]>2026-11-10 15:20:24 -0300
commit6fb92d5384ba944b2d6a9c5066a08b41a8ef555f (patch)
treef8854c4272879c5fb54b7fd0e7c2f0e0b8ab904a /design/mock/context.py
parent2463e602f12f969fe085bc2114a3960411b79f87 (diff)
downloadcomputeranim-6fb92d5384ba944b2d6a9c5066a08b41a8ef555f.tar.gz
computeranim-6fb92d5384ba944b2d6a9c5066a08b41a8ef555f.zip
design: a language of named blocks; the lens as a band over the whole context
The README is now the catalogue: atoms, rows, panels, ties, the frame and the verbs, each block specified once under the name the code uses, with rules of composition and what is forbidden. From the user's notes on the context mocks: a lens is a band across the top, its drawing on the left and the bytes it is drawn from on the right, a hexdump with each field's bytes marked and read at the row's end; the disassembly is seventeen rows in address order with a source-line column and an annotation for what each row read, set or jumped to; a register is pinned to the node it points at by name; hex is unbroken; and four kinds of tie say which pane is a view of which (thread, link, projection, echo).
Diffstat (limited to 'design/mock/context.py')
-rw-r--r--design/mock/context.py563
1 files changed, 341 insertions, 222 deletions
diff --git a/design/mock/context.py b/design/mock/context.py
index 8a5d923..886372f 100644
--- a/design/mock/context.py
+++ b/design/mock/context.py
@@ -1,26 +1,33 @@
#!/usr/bin/env python3
-"""The default frame: the machine's whole context, pwndbg's way, and the scene's lens.
+"""The frame: the machine's whole context, pwndbg's way, a lens over it, and the ties between them.
python3 context.py # writes 09-context.svg, 10-context-step.svg, 11-context-lens.svg
+Every function here is a block of design/README.md, under the block's name.
+
The moment is real: `ztrace record --by line -- targets/list`, moments 71 and 72
-(`ztrace show FILE 71`): every register and its chain, the instructions at the pc, the
-stack. The lens (the list, and the heap words that are its nodes) is what those chains
-and the program say the heap holds; a recording made under ptrace has no allocations.
+(`ztrace show FILE 71`): every register and its chain, the stack, and the instructions
+of `reverse` with their lines (objdump -dl). The dump's node bytes are what those chains
+and the program say the heap holds. Its header rows are drawn the way glibc lays a chunk
+out, with the word no one reads shown as never read: a recording made under ptrace has
+seen neither.
"""
import re
import gen
-from gen import (PAGE, RAISED, RULE, VELLUM, BRIGHT, DIM, FAINT, INK, GOLD, VERM, READ, ALLOC, EMBER, TRAIL,
- STACK, HEAP, CODE, DATA, KW, LIT, COMMENT, W, H, Svg, tw)
+from gen import (PAGE, RAISED, RULE, VELLUM, BRIGHT, DIM, FAINT, INK, GOLD, VERM, READ, EMBER, TRAIL,
+ STACK, HEAP, CODE, DATA, KW, LIT, COMMENT, W, Svg, tw, mix)
S = 20 # the context's mono size: an advance of 12
A = 12
ROW = 24
TAG = 24
+PAD = 4 # above and below a panel's rows
MONO, BOLD, ITAL = "monom", "monob", "monoi"
-LX, RX, CW = 64, 976, 880 # the two columns
+LX, RX, CW = 64, 976, 880 # the two columns; the gutter between them is the ties' channel
TOP, BOTTOM = 48, 888 # the stage
+LANE_LINK, LANE_VIEW = 950, 962 # the gutter's lanes: a link comes up the first, a projection down the second
+WELL = "#101a48" # a node's pointer half
def b(y):
@@ -28,9 +35,13 @@ def b(y):
return y + ROW / 2 + 0.36 * S
-def panel(g, x, y, w, rows, title, focus=False, note=None, h=None):
- """A one-row tag and `rows` rows under it. Returns the y of the first row."""
- h = h or TAG + 12 + rows * ROW
+def ph(rows):
+ """A panel's height."""
+ return TAG + 2 * PAD + rows * ROW
+
+
+def tag(g, x, y, w, h, title, focus=False, note=None):
+ """A panel's frame and its one-row tag. note: a string, or runs (text, ink, underlined) for a legend."""
g.rect(x, y, w, TAG, RAISED)
g.frame(x, y, w, h, DIM if focus else RULE, 2)
if focus:
@@ -40,52 +51,67 @@ def panel(g, x, y, w, rows, title, focus=False, note=None, h=None):
g.t(x + 28, y + 18, title, 20, VELLUM if focus else DIM, "sansm")
if isinstance(note, str):
g.t(x + w - 10, y + 18, note, 18, FAINT, "sans", "end")
- elif note: # runs, each in its own ink: the legend
+ elif note:
nx = x + w - 10 - sum(tw(s, 18, "sansm") + 14 for s, _, _ in note) + 14
for s, ink, under in note:
g.t(nx, y + 18, s, 18, ink, "sansm")
if under:
g.rect(nx, y + 21, tw(s, 18, "sansm"), 2, ink)
nx += tw(s, 18, "sansm") + 14
- return y + TAG + 6
-# ---- a value, by what it is ---------------------------------------------------
-def groups(n):
- """Hex at its natural length, in fours from the right."""
- d = "%x" % n
- head = len(d) % 4
- return ([d[:head]] if head else []) + [d[i:i + 4] for i in range(head, len(d), 4)]
+def panel(g, x, y, w, rows, title, focus=False, note=None):
+ """Returns the y of the first row."""
+ tag(g, x, y, w, ph(rows), title, focus, note)
+ return y + TAG + PAD
+# ---- atoms ----------------------------------------------------------------------
def addr_w(n):
- gs = groups(n)
- return sum(len(s) for s in gs) * A + (len(gs) - 1) * (A // 2)
+ return len("%x" % n) * A
-def addr(g, x, y, n, ink, face=MONO, under=False):
- for s in groups(n):
- g.t(x, b(y), s, S, ink, face)
- x += len(s) * A + A // 2
+def shared(ns):
+ """How many leading digits a column of addresses has in common: drawn dim, so the eye reads the rest."""
+ ds = ["%x" % n for n in ns]
+ k = 0
+ while all(len(d) == len(ds[0]) and d[:k + 1] == ds[0][:k + 1] for d in ds) and k < len(ds[0]) - 2:
+ k += 1
+ return k
+
+
+def addr(g, x, y, n, ink, face=MONO, under=False, lead=0):
+ """An address: its digits, unbroken, in its region's ink."""
+ d = "%x" % n
+ if lead:
+ g.t(x, b(y), d[:lead], S, mix(ink, PAGE, 0.6), face)
+ g.t(x + lead * A, b(y), d[lead:], S, ink, face)
if under: # writable and executable
- g.rect(x - addr_w(n) - A // 2, y + ROW - 3, addr_w(n), 2, ink)
- return x - A // 2
+ g.rect(x, y + ROW - 3, len(d) * A, 2, ink)
+ return x + len(d) * A
def link_arrow(g, x, y, ink=FAINT):
- """A pointer to: 30 wide."""
+ """Points to: 30 wide."""
g.rect(x + 6, y + 11, 11, 2, ink)
g.path(f"M{x + 24},{y + 12} l-8,-5 v10 Z", fill=ink)
return x + 30
def value_arrow(g, x, y, ink=FAINT):
- """Which holds: 30 wide, pointing back."""
+ """Holds: 30 wide, pointing back."""
g.path(f"M{x + 6},{y + 12} l8,-5 v10 Z", fill=ink)
g.rect(x + 13, y + 11, 11, 2, ink)
return x + 30
+def more(g, x, y):
+ """The chain goes on: an arrow and three dots."""
+ x = link_arrow(g, x, y)
+ for d in range(3):
+ g.rect(x + 2 + d * 8, y + 14, 3, 3, FAINT)
+
+
def integer(g, x, y, v, ink=VELLUM):
"""A number that is not an address: one digit as it is; more, hex with 0x and its decimal after, faint."""
if v < 10:
@@ -100,17 +126,21 @@ def integer(g, x, y, v, ink=VELLUM):
return x
-def chain(g, x, y, links, end, marks=None, room=None):
- """A telescope: links are (address, ink[, name]); end is ("int", v), ("str", s), ("more",) or None.
- marks: {index: "strike" | "tick" | "read" | "land"} on a link, index len(links) being the end.
+def chain(g, x, y, links, end, marks=None, room=None, lead=0):
+ """A telescope: links are (address, ink[, name]); end is ("int", v), ("str", s) or None.
+ marks: {index: "strike" | "tick" | "read"} on a link. Cut at its far end where the row ends.
Returns each link's (x, width)."""
marks = marks or {}
where = []
for i, link in enumerate(links):
n, ink = link[0], link[1]
+ w = addr_w(n)
+ named = (10 + len(link[2]) * A) if len(link) > 2 else 0
if i:
+ if room is not None and x + 30 + w + named + 40 > room:
+ more(g, x, y)
+ return where
x = link_arrow(g, x, y)
- w = addr_w(n)
m = marks.get(i)
if m == "strike":
g.rect(x - 5, y + 1, w + 10, ROW - 2, VERM)
@@ -120,53 +150,59 @@ def chain(g, x, y, links, end, marks=None, room=None):
g.rect(x - 9, y + 3, 4, ROW - 6, VERM)
if m == "read":
g.frame(x - 6, y, w + 12, ROW, READ, 2)
- if m == "land":
- g.frame(x - 6, y, w + 12, ROW, BRIGHT, 2)
- addr(g, x, y, n, ink)
+ addr(g, x, y, n, ink, lead=lead if i == 0 else 0)
where.append((x, w))
x += w
- if len(link) > 2: # code: its name is what a reader reads
+ if named: # code: its name is what a reader reads
g.t(x + 10, b(y), link[2], S, VELLUM, MONO)
- x += 10 + len(link[2]) * A
+ x += named
if end is None:
return where
- if end[0] == "more":
- x = link_arrow(g, x, y)
- for d in range(3):
- g.rect(x + 2 + d * 8, y + 14, 3, 3, FAINT)
- return where
x = value_arrow(g, x, y) if links else x
- m = marks.get(len(links))
- if m == "tick":
- g.rect(x - 3, y + 3, 4, ROW - 6, VERM)
- x += 6
if end[0] == "int":
integer(g, x, y, end[1])
else:
s = end[1]
if room is not None and len(s) + 2 > (room - x) // A:
- s = s[:max(int((room - x) // A) - 2, 1)] + "…"
- g.t(x, b(y), '"' + s, S, LIT, MONO)
+ g.t(x, b(y), '"' + s[:max(int((room - x) // A) - 2, 1)] + "…", S, LIT, MONO)
else:
g.t(x, b(y), '"' + s + '"', S, LIT, MONO)
return where
-def plaque(g, x, y, s, fill=RAISED, ink=VELLUM, stroke=None, pad=4):
- """A register's name where it points: 20 tall in a 24 row."""
- w = len(s) * A + 2 * pad
- g.rect(x, y + 2, w, ROW - 4, fill)
- if stroke:
- g.frame(x, y + 2, w, ROW - 4, stroke, 2)
- g.t(x + pad, b(y) - 1, s, S, ink, MONO)
- return w
+def pin(g, x, y, names, ink):
+ """A register's name where it points, in a row: the names, and a head on what they point at."""
+ s = " ".join(names)
+ g.t(x, b(y), s, S, VELLUM, BOLD)
+ x += len(s) * A + 5
+ g.path(f"M{x + 9},{y + 12} l-9,-6 v12 Z", fill=ink)
+
+
+def pin_up(g, cx, y, names, ink, size, link=None):
+ """A register's name under what it points at: a stub with its head on the thing, the names either side.
+ link: the points the stub is the end of, when this is the step that set the register."""
+ rise = size + 10
+ gen.arrow(g, (link or []) + [(cx, y + rise), (cx, y + 1)], ink, 3, r=8, hl=10, hw=10)
+ face = BOLD
+ by = y + 8 + size * 0.86
+ if names:
+ g.t(cx - 9, by, names[0], size, VELLUM, face, "end")
+ if len(names) > 1:
+ g.t(cx + 9, by, " ".join(names[1:]), size, VELLUM, face)
-# ---- the context's five panels ---------------------------------------------------
+def bracket(g, x, y0, y1, ink, sw=2, serif=5, side=1):
+ """A span of rows, marked at its edge: the end of a projection, or a thing that is a view of another."""
+ g.rect(x - sw / 2, y0, sw, y1 - y0, ink)
+ for yy in (y0, y1 - sw):
+ g.rect(x - sw / 2 if side > 0 else x + sw / 2 - serif - sw, yy, serif + sw, sw, ink)
+
+
+# ---- the state column ---------------------------------------------------------------
def registers(g, y, regs, flags, marks):
legend = [("stack", STACK, False), ("heap", HEAP, False), ("code", CODE, False), ("data", DATA, False),
("rwx", DATA, True), ("read-only", VELLUM, False)]
- y0 = panel(g, RX, y, CW, 18, "registers", note=legend)
+ y0 = panel(g, RX, y, CW, 17, "registers", note=legend)
where = {}
for i, (name, links, end) in enumerate(regs):
yy = y0 + i * ROW
@@ -176,53 +212,53 @@ def registers(g, y, regs, flags, marks):
g.t(RX + 12, b(yy), name, S, INK, BOLD)
else:
g.t(RX + 12, b(yy), name, S, DIM, MONO)
- where[name] = (yy, chain(g, RX + 72, yy, links, end, marks.get(name), room=RX + CW - 12) if links else
- [(RX + 72, integer(g, RX + 72, yy, end[1]) - RX - 72)])
- if not links and marks.get(name, {}).get(0) == "tick":
- g.rect(RX + 63, yy + 3, 4, ROW - 6, VERM)
- yy = y0 + 17 * ROW
- g.t(RX + 12, b(yy), "flags", S, DIM, MONO)
- g.t(RX + 84, b(yy), "0x%x" % flags[0], S, VELLUM, MONO)
- x = RX + 84 + 6 * A + 12
- for name, on, changed in flags[1]:
+ where[name] = yy
+ if links:
+ chain(g, RX + 72, yy, links, end, marks.get(name), room=RX + CW - 12)
+ else:
+ integer(g, RX + 72, yy, end[1])
+ if marks.get(name, {}).get(0) == "tick":
+ g.rect(RX + 63, yy + 3, 4, ROW - 6, VERM)
+ # the flags, in rip's row: where the machine is, and the condition it is in
+ x = RX + CW - 12 - len(flags) * 42 + 10
+ for name, on, changed in flags:
if changed:
g.rect(x - 7, yy + 3, 4, ROW - 6, VERM)
if on:
g.rect(x, yy + 2, 2 * A + 8, 20, RAISED)
g.t(x + 4, b(yy), name, S, BRIGHT, BOLD)
else:
- g.t(x + 4, b(yy), name.lower(), S, FAINT, MONO)
- x += 2 * A + 8 + 10
+ g.t(x + 4, b(yy), name.lower(), S, mix(DIM, EMBER[GOLD], 0.8), MONO)
+ x += 42
return where
-def stack(g, y, rows):
- y0 = panel(g, RX, y, CW, len(rows), "stack", note="eight words from rsp · low addresses on top")
- where = {}
- for i, (slot, names, links, end, note) in enumerate(rows):
+def stack(g, y, rows, frames):
+ """rows: (slot, pins, links, end). frames: (name, first row, last row), newest first: the backtrace,
+ drawn on the words that are each frame."""
+ y0 = panel(g, RX, y, CW, len(rows), "stack", note="%s words from rsp · the frames they belong to" %
+ {4: "four", 8: "eight"}[len(rows)])
+ lead = shared([r[0] for r in rows])
+ for i, (slot, pins, links, end) in enumerate(rows):
yy = y0 + i * ROW
- x = RX + 10
- for n in names:
- x += plaque(g, x, yy, n, stroke=STACK, pad=2) + 2
- where[slot] = yy
- chain(g, RX + 104, yy, [(slot, STACK)] + links, end, room=RX + CW - 8)
- if note:
- g.t(RX + CW - 12, b(yy) - 1, note, 18, FAINT, "sans", "end")
- return where
-
-
-def backtrace(g, y, frames):
- y0 = panel(g, RX, y, CW, len(frames), "backtrace", note="newest on top")
- for i, (name, where_) in enumerate(frames):
- yy = y0 + i * ROW
- if i == 0:
- g.rect(RX + 2, yy, CW - 4, ROW, EMBER[GOLD])
- g.rect(RX + 2, yy, 42, ROW, GOLD)
- g.t(RX + 12, b(yy), "#%d" % i, S, INK if i == 0 else FAINT, BOLD if i == 0 else MONO)
- g.t(RX + 60, b(yy), name, S, VELLUM, MONO)
- g.t(RX + 60 + 18 * A, b(yy), where_, S, DIM, MONO)
+ if pins:
+ pin(g, RX + 10, yy, pins, STACK)
+ chain(g, RX + 122, yy, [(slot, STACK)] + links, end, room=RX + CW - 136, lead=lead)
+ for i, (name, first, last) in enumerate(frames):
+ if first >= len(rows):
+ break
+ ink = GOLD if i == 0 else RULE
+ open_ = last >= len(rows)
+ last = min(last, len(rows) - 1)
+ x, ya, yb = RX + CW - 14, y0 + first * ROW + 3, y0 + (last + 1) * ROW - (0 if open_ else 3)
+ g.rect(x - 1, ya, 2, yb - ya, ink)
+ g.rect(x - 7, ya, 8, 2, ink)
+ if not open_:
+ g.rect(x - 7, yb - 2, 8, 2, ink)
+ g.t(x - 14, (ya + yb) / 2 + 6, name, 18, BRIGHT if i == 0 else DIM, "sansm", "end")
+# ---- the program column -------------------------------------------------------------
C_WORDS = {"struct", "long", "static", "return", "while", "for", "int", "char", "sizeof", "if", "else", "void", "NULL",
"__attribute__", "noinline"}
@@ -249,6 +285,7 @@ def c_line(g, x, y, text, limit):
def source(g, y, rows, lines, first, cur, trail, name, total):
+ """Returns the y of the current line's row."""
y0 = panel(g, LX, y, CW, rows, name, note=f"lines {first} to {first + rows - 1} of {total}")
for i in range(rows):
n = first + i
@@ -262,120 +299,195 @@ def source(g, y, rows, lines, first, cur, trail, name, total):
g.rect(LX + 2, yy + 1, 4, ROW - 2, TRAIL[min(trail.index(n), 2)])
g.t(LX + 46, b(yy), str(n), S, FAINT, MONO, "end")
c_line(g, LX + 64, yy, lines[n - 1], (CW - 64 - 12) // A)
+ return y0 + (cur - first) * ROW
+
+DX_ADDR, DX_LINE, DX_MN, DX_OPS, DX_NOTE = 40, 134, 180, 264, 564
-def disasm(g, y, rows, func):
- """rows: (address, offset, mnemonic, operands, state) with state in cur | trail0 | trail1 | None,
- or ("note", parts) for the row under the pc that says what its operand is."""
+
+def disasm(g, y, rows, func, cur_line, jump=None):
+ """rows: (address, line, mnemonic, operands, state, note), in address order: the pc's row and as many
+ above as below. state: cur | trail0..2 (it ran just now) | out (past the function's end) | None.
+ note, the row's annotation: ("chain", links, end, marks) | ("set", register, links, end) | ("text", s).
+ jump: (from, to): a jump that was taken, drawn in the lane.
+ Returns each address's row y."""
y0 = panel(g, LX, y, CW, len(rows), "disassembly", note=func)
- where = {}
- for i, r in enumerate(rows):
+ lead = shared([r[0] for r in rows if r[4] != "out"])
+ where, last_line = {}, None
+ for i, (a, line, mn, ops, st, note) in enumerate(rows):
yy = y0 + i * ROW
- if r[0] == "note":
- g.rect(LX + 2, yy, CW - 4, ROW, EMBER[GOLD])
- g.t(LX + 198, b(yy), r[1], S, DIM, MONO)
- x = LX + 198 + (len(r[1]) + 1) * A
- where["note"] = (yy, chain(g, x, yy, r[2], r[3], r[4] if len(r) > 4 else None))
- continue
- a, off, mn, ops, st = r
+ where[a] = yy
+ dim = st == "out"
+ if dim: # the function ends: a rule, and the next one's name
+ g.rect(LX + 2, yy, CW - 4, 2, RULE)
if st == "cur":
g.rect(LX + 2, yy, CW - 4, ROW, EMBER[GOLD])
- g.rect(LX + 2, yy, 26, ROW, GOLD)
- g.path(f"M{LX + 21},{yy + 12} l-10,-6 v12 Z", fill=INK)
- elif st:
+ g.rect(LX + 2, yy, 24, ROW, GOLD)
+ g.path(f"M{LX + 20},{yy + 12} l-10,-6 v12 Z", fill=INK)
+ elif st and st.startswith("trail"):
g.rect(LX + 2, yy + 1, 4, ROW - 2, TRAIL[int(st[-1])])
- addr(g, LX + 36, yy, a, CODE)
- g.t(LX + 138, b(yy), "+%d" % off, S, FAINT, MONO)
- g.t(LX + 198, b(yy), mn, S, KW, BOLD)
- x = LX + 198 + 6 * A
+ addr(g, LX + DX_ADDR, yy, a, mix(CODE, PAGE, 0.6) if dim else CODE, lead=0 if dim else lead)
+ if line != last_line and not dim: # the line this run of instructions was compiled from
+ on = line == cur_line
+ g.t(LX + DX_LINE + 3 * A, b(yy), str(line), S, GOLD if on else FAINT, BOLD if on else MONO, "end")
+ last_line = line
+ g.t(LX + DX_MN, b(yy), mn, S, FAINT if dim else KW, MONO if dim else BOLD)
+ x = LX + DX_OPS
for part, ink in ops:
if isinstance(part, int):
- x = addr(g, x, yy, part, ink) + 0
+ x = addr(g, x, yy, part, ink)
else:
- g.t(x, b(yy), part, S, ink, MONO)
+ g.t(x, b(yy), part, S, FAINT if dim else ink, MONO)
x += len(part) * A
- where[a] = yy
+ if not note:
+ continue
+ x = LX + DX_NOTE
+ if note[0] == "text":
+ g.t(x, b(yy), note[1], S, note[2] if len(note) > 2 else DIM, MONO)
+ elif note[0] == "set": # what an instruction that ran left in a register: a register row, small
+ g.t(x, b(yy), note[1], S, DIM, MONO)
+ chain(g, x + (len(note[1]) + 1) * A, yy, note[2], note[3], room=LX + CW - 12)
+ else:
+ where["note"] = (yy, chain(g, x, yy, note[1], note[2], note[3], room=LX + CW - 12))
+ if jump: # how control came here: up the lane, into the row it landed on
+ ya, yb = where[jump[0]] + 12, where[jump[1]] + 12
+ gen.arrow(g, [(LX + 38, ya), (LX + 31, ya), (LX + 31, yb), (LX + 39, yb)], TRAIL[0], 2, r=4, hl=7, hw=8)
return where
-# ---- the lens: a list, and the heap words that are its nodes ----------------------
-def lens(g, y, nodes, pointing, marks, h=312, subject=False):
- """nodes: (address, value, next address or 0), in the list's first order. pointing: {address: [registers]}.
- marks: {"read": address of a word, "tick": [...], "land": address of a node}.
- As the subject it is one size up: mono 25 on rows of 30."""
- global S, A, ROW
- keep = (S, A, ROW)
- panel(g, LX, y, CW, 0, "the list", focus=True, note="each node, and under it the heap words that are that node", h=h)
- if subject:
- S, A, ROW = 25, 15, 30
- NW, NH, GAP = (124, 64, 22) if subject else (116, 44, 28)
+def thread(g, ys, spans):
+ """The gold thread: the source's current line and the instructions it was compiled to are one mark.
+ A bracket on the line, a bracket on each run of its instructions, and a line in the margin between."""
+ x = LX - 10
+ bracket(g, x, ys + 2, ys + ROW - 2, GOLD, 3, 7)
+ for ya, yb in spans:
+ bracket(g, x, ya + 2, yb - 2, GOLD, 3, 7)
+ g.rect(x - 1.5, ys + 2, 3, spans[-1][1] - 2 - ys - 2, GOLD)
+
+
+# ---- the lens: a list, and beside it the bytes it is drawn from -------------------------
+def dump_row(g, y, a, runs, lead, mark=None, node=False):
+ """A hexdump row: sixteen bytes and what they read as. runs: (first byte, bytes, kind, value) with kind
+ in value | next | malloc | unread. mark: {"read": run index, "tick": run index}."""
+ mark = mark or {}
+ bx = lambda i: RX + 132 + i * 30 + (12 if i >= 8 else 0)
+ addr(g, RX + 18, y, a, HEAP if node else mix(HEAP, PAGE, 0.6), lead=lead)
+ for k, (i0, n, kind, v) in enumerate(runs):
+ x0, x1 = bx(i0) - 4, bx(i0 + n - 1) + 28
+ if kind in ("value", "next"):
+ g.rect(x0, y + 1, x1 - x0, ROW - 2, RAISED)
+ if mark.get("read") == k:
+ g.frame(x0 - 3, y - 1, x1 - x0 + 6, ROW + 2, READ, 2)
+ if mark.get("tick") == k:
+ g.rect(x0 - 7, y + 3, 4, ROW - 6, VERM)
+ ink = {"value": VELLUM, "next": HEAP, "malloc": DIM, "unread": FAINT}[kind]
+ top = max((j for j in range(n) if (v or 0) >> (8 * j) & 0xff), default=0)
+ for j in range(n):
+ x = bx(i0 + j)
+ if kind == "unread": # never read: two dots a byte
+ g.rect(x + 5, y + 11, 4, 4, FAINT)
+ g.rect(x + 15, y + 11, 4, 4, FAINT)
+ continue
+ # little-endian: the bytes above the highest one set are padding, and faint
+ g.t(x, b(y), "%02x" % (v >> (8 * j) & 0xff), S, ink if j <= top else mix(ink, PAGE, 0.45), MONO)
+ # what the row reads as
+ x = RX + 640
+ if not node:
+ g.t(x, b(y) - 1, "malloc's: a chunk of 32", 18, FAINT, "sans")
+ return
+ value, nxt = runs[0][3], runs[1][3]
+ g.t(x + 3 * A, b(y), str(value), S, VELLUM, MONO, "end")
+ if nxt:
+ addr(g, link_arrow(g, x + 3 * A + 8, y), y, nxt, HEAP)
+ else:
+ g.t(x + 3 * A + 8 + 30, b(y), "NULL", S, DIM, MONO)
+
+
+def lens(g, y, h, nodes, pins, marks, first, nrows, link_from=None, subject=False):
+ """The band: the list drawn, and the heap bytes it is drawn from, in one panel across both columns.
+ nodes: (address, value, next address or 0), in the list's order. pins: {address: [registers]}.
+ marks: {"read": address of a word, "tick": [addresses of words]}.
+ link_from: the y of the register row the step's link comes from, and the register.
+ As the subject the drawing is a size up; the dump stays on the context's grid and shows more rows."""
+ tag(g, LX, y, W - 2 * LX, h, "the list", focus=True,
+ note=[("value", VELLUM, False), ("next", HEAP, False), ("malloc's", DIM, False), ("never read", FAINT, False)])
+ last = first + (nrows - 1) * 16
+ g.t(RX + 12, y + 18, "its bytes", 20, VELLUM, "sansm")
+ g.t(RX + 12 + tw("its bytes", 20, "sansm") + 12, y + 18, "the heap, %x to %x" % (first, last + 15), 18, FAINT, "sans")
+
+ # the dump
+ y0 = y + TAG + PAD
+ by_addr = {a: (v, nx) for a, v, nx in nodes}
+ lead = shared([first, last])
+ rows = {}
+ for i in range(nrows):
+ a, yy = first + i * 16, y0 + i * ROW
+ rows[a] = yy
+ if a in by_addr:
+ v, nx = by_addr[a]
+ m = {}
+ if marks.get("read") == a + 8:
+ m["read"] = 1
+ if a + 8 in marks.get("tick", ()):
+ m["tick"] = 1
+ dump_row(g, yy, a, [(0, 8, "value", v), (8, 8, "next", nx)], lead, m, node=True)
+ if marks.get("read") != a + 8:
+ bracket(g, RX + 7, yy + 3, yy + ROW - 3, mix(HEAP, PAGE, 0.6))
+ else:
+ dump_row(g, yy, a, [(0, 8, "unread", None), (8, 8, "malloc", 0x21)], lead)
+
+ # the drawing
+ NW, NH, GAP, VS, LS = (124, 72, 22, 45, 25) if subject else (116, 44, 28, 25, 20)
VW = NW - 48 # the value's half; the pointer's is 48
x0 = LX + (CW - len(nodes) * NW - (len(nodes) - 1) * GAP) / 2
- ny = y + TAG + (22 if subject else 14)
+ lane_top, lane_bot = y + TAG + 4, y + h - 8
+ ly = y + TAG + (44 if subject else 16) # the row of addresses over the nodes
+ ny = ly + LS * 1.2 + 4
xs = {a: x0 + i * (NW + GAP) for i, (a, v, nx) in enumerate(nodes)}
for a, v, nx in nodes:
x = xs[a]
+ g.t(x + NW / 2, ly + LS * 0.96, "%x" % a, LS, HEAP, MONO, "middle")
g.rect(x, ny, VW - 2, NH, RAISED)
- vs = 35 if subject else 25
- g.t(x + VW / 2 - 1, ny + NH / 2 + 0.36 * vs, str(v), vs, VELLUM, MONO if vs < 30 else "mono", "middle")
- g.rect(x + VW, ny, NW - VW, NH, "#101a48")
+ g.t(x + VW / 2 - 1, ny + NH / 2 + 0.36 * VS, str(v), VS, VELLUM, MONO if VS < 30 else "mono", "middle")
+ g.rect(x + VW, ny, NW - VW, NH, WELL)
if marks.get("read") == a + 8:
g.frame(x + VW - 2, ny - 2, NW - VW + 4, NH + 4, READ, 2)
if a + 8 in marks.get("tick", ()):
g.rect(x + VW, ny + NH - 4, NW - VW, 4, VERM)
- if marks.get("land") == a:
- g.frame(x - 4, ny - 4, NW + 8, NH + 8, BRIGHT, 2)
cx, cy = x + VW + (NW - VW) / 2, ny + NH / 2
if nx:
g.rect(cx - 5, cy - 5, 10, 10, HEAP)
- tx = xs[nx]
- if tx > x:
- gen.arrow(g, [(cx + 8, cy), (tx - 3, cy)], HEAP, 3, hl=12, hw=10)
- else: # a link turned round: under the row
- gen.arrow(g, [(cx, cy + 8), (cx, ny + NH + 12), (tx + 34, ny + NH + 12), (tx + 34, ny + NH + 3)], HEAP, 3, r=8, hl=12, hw=10)
+ gen.arrow(g, [(cx + 8, cy), (xs[nx] - 3, cy)], HEAP, 3, hl=12, hw=10)
else:
g.path(f"M{x + VW + 10},{ny + NH - 8} L{x + NW - 10},{ny + 8}", DIM, 2)
- addr(g, x + (NW - addr_w(a)) / 2, ny + NH + 2, a, HEAP)
- px = x + 2
- for name in pointing.get(a, ()):
- px += plaque(g, px, ny + NH + ROW + 2, name, stroke=HEAP) + 4
- # the words
- wy = ny + NH + 2 * ROW + (46 if subject else 34)
- c0, c1, c2 = (LX + 190, LX + 380, LX + 590) if subject else (LX + 150, LX + 300, LX + 470)
- g.t(c0, wy - 6, "address", 18, FAINT, "sansm")
- g.t(c1, wy - 6, "value", 18, FAINT, "sansm")
- g.t(c2, wy - 6, "next", 18, FAINT, "sansm")
- if not subject:
- g.t(LX + CW - 12, wy - 6, "the heap, sixteen bytes a node", 18, FAINT, "sans", "end")
- rows = {}
- for i, (a, v, nx) in enumerate(sorted(nodes)):
- yy = wy + i * ROW
- rows[a] = yy
- px = LX + 12
- for name in pointing.get(a, ()):
- px += plaque(g, px, yy, name, stroke=HEAP) + 4
- if marks.get("land") == a:
- g.frame(c0 - 6, yy, c2 - c0 + addr_w(a) + 12, ROW, BRIGHT, 2)
- addr(g, c0, yy, a, HEAP)
- integer(g, c1, yy, v)
- if a + 8 in marks.get("tick", ()):
- g.rect(c2 - 9, yy + 3, 4, ROW - 6, VERM)
- if marks.get("read") == a + 8:
- g.frame(c2 - 6, yy, addr_w(a) + 12, ROW, READ, 2)
- if nx:
- addr(g, c2, yy, nx, HEAP)
- else:
- g.t(c2, b(yy), "0", S, VELLUM, MONO)
- g.t(c2 + 2 * A, b(yy), "NULL", S, FAINT, MONO)
- land_x = c2 + addr_w(nodes[0][0]) + 10
- S, A, ROW = keep
- return xs, rows, land_x
+ names = pins.get(a)
+ if names:
+ via = None
+ if link_from and link_from[1] in names: # the step's link ends in this pin
+ names = [link_from[1]] + [n for n in names if n != link_from[1]]
+ via = [(RX + 2, link_from[0] + 12), (LANE_LINK, link_from[0] + 12), (LANE_LINK, lane_bot),
+ (x + NW / 2, lane_bot)]
+ pin_up(g, x + NW / 2, ny + NH, names, HEAP, LS, via)
+
+ # the projection: the bytes a step read, and the part of the drawing that is those bytes
+ if marks.get("read"):
+ a = marks["read"] & ~15
+ yy, x = rows[a], xs[a]
+ bracket(g, RX + 7, yy + 2, yy + ROW - 2, READ, 3, 6)
+ g.path(f"M{RX + 6},{yy + 12} H{LANE_VIEW + 6} Q{LANE_VIEW},{yy + 12} {LANE_VIEW},{yy + 6} V{lane_top + 6} "
+ f"Q{LANE_VIEW},{lane_top} {LANE_VIEW - 6},{lane_top} H{x + NW / 2 + 6} "
+ f"Q{x + NW / 2},{lane_top} {x + NW / 2},{lane_top + 6} V{ly - 4}", READ, 2)
+ g.rect(x, ly - 5, NW, 3, READ)
+ g.rect(x, ly - 5, 3, 8, READ)
+ g.rect(x + NW - 3, ly - 5, 3, 8, READ)
+ return xs, rows
-# ---- the data: moments 71 and 72 of the recording -----------------------------------
+# ---- the data: moments 71 and 72 of the recording ---------------------------------------
SRC = open(__file__.replace("context.py", "list.c")).read().split("\n")
S_, H_, C_, D_ = STACK, HEAP, CODE, DATA
RBP = [(0x7ffe970f17b0, S_), (0x7ffe970f17d0, S_), (0x7ffe970f1880, S_), (0x7ffe970f18e0, S_)]
+ARGV = [(0x7ffe970f1908, S_), (0x7ffe970f2fce, S_)]
def regs_at(rdi):
@@ -392,7 +504,7 @@ def regs_at(rdi):
("r9", [], ("int", 0x20)),
("r10", [], ("int", 0x10)),
("r11", [(0x7f2ba3019ac8, D_), (0x28b410c0, H_)], ("int", 0)),
- ("r12", [(0x7ffe970f1908, S_), (0x7ffe970f2fce, S_)], ("str", "zig-out/targets/list")),
+ ("r12", ARGV, ("str", "zig-out/targets/list")),
("r13", [], ("int", 1)),
("r14", [(0x7f2ba32ac000, D_), (0x7f2ba32ad3c0, D_)], ("int", 0)),
("r15", [(0x10029c0, VELLUM)], ("int", 1)),
@@ -400,81 +512,88 @@ def regs_at(rdi):
]
+FLAGS = [("CF", 0, 0), ("PF", 1, 0), ("AF", 0, 0), ("ZF", 0, 1), ("SF", 0, 0), ("IF", 1, 0), ("DF", 0, 0), ("OF", 0, 0)]
STACK_ROWS = [
- (0x7ffe970f17b0, ["rsp", "rbp"], RBP[1:], ("int", 0), ""),
- (0x7ffe970f17b8, [], [(0x10018b0, C_, "main+80")], None, "return address"),
- (0x7ffe970f17c0, [], [(0x7f2ba3020de8, D_), (0x7ffe970f1918, S_)], ("more",), ""),
- (0x7ffe970f17c8, [], [], ("int", 0), ""),
- (0x7ffe970f17d0, [], RBP[2:], ("int", 0), "main's saved rbp"),
- (0x7ffe970f17d8, [], [(0x7f2ba2e27781, C_, "libc+27781")], None, "return address"),
- (0x7ffe970f17e0, [], [(0x7f2ba328fc60, C_, "ld.so+22c60")], None, ""),
- (0x7ffe970f17e8, [], [(0x7ffe970f1908, S_), (0x7ffe970f2fce, S_)], ("str", "zig-out/targets/list"), ""),
+ (0x7ffe970f17b0, ["rsp", "rbp"], RBP[1:], ("int", 0)),
+ (0x7ffe970f17b8, [], [(0x10018b0, C_, "main+80")], None),
+ (0x7ffe970f17c0, [], [(0x7f2ba3020de8, D_), (0x7ffe970f1918, S_), (0x7ffe970f2fe3, S_)], ("str", "SHELL=/usr/bin/bash")),
+ (0x7ffe970f17c8, [], [], ("int", 0)),
+ (0x7ffe970f17d0, [], RBP[2:], ("int", 0)),
+ (0x7ffe970f17d8, [], [(0x7f2ba2e27781, C_, "libc+27781")], None),
+ (0x7ffe970f17e0, [], [(0x7f2ba328fc60, C_, "ld.so+22c60")], None),
+ (0x7ffe970f17e8, [], ARGV, ("str", "zig-out/targets/list")),
]
-FRAMES = [("reverse+22", "list.c:21"), ("main+80", "list.c:39"), ("libc+27781", "libc.so.6")]
+FRAMES = [("reverse", 0, 1), ("main", 2, 5), ("libc+27781", 6, 8)]
NODES = [(0x28b410b0, 1, 0), (0x28b41090, 4, 0x28b41070), (0x28b41070, 9, 0x28b41050),
(0x28b41050, 16, 0x28b41030), (0x28b41030, 25, 0x28b41010), (0x28b41010, 36, 0)]
P = VELLUM
-DIS = [
- (0x1001920, 16, "mov", [("rcx, rax", P)], "trail1"),
- (0x1001923, 19, "mov", [("rax, rdi", P)], "trail0"),
- (0x1001926, 22, "mov", [("rdi, qword ptr [rdi + 8]", P)], "cur"),
- None, # the note, filled in by each frame
- (0x100192a, 26, "mov", [("qword ptr [rax + 8], rcx", P)], None),
- (0x100192e, 30, "test", [("rdi, rdi", P)], None),
+RAX = ("set", "rax", [(0x28b41090, H_)], ("int", 4))
+RCX = ("set", "rcx", [(0x28b410b0, H_)], ("int", 1))
+DIS = [ # address, line, mnemonic, operands, state, annotation
+ (0x1001910, 20, "test", [("rdi, rdi", P)], None, None),
+ (0x1001913, 20, "je", [(0x1001935, C_)], None, None),
+ (0x1001915, 20, "push", [("rbp", P)], None, None),
+ (0x1001916, 20, "mov", [("rbp, rsp", P)], None, None),
+ (0x1001919, 20, "xor", [("eax, eax", P)], None, None),
+ (0x100191b, 20, "nop", [("dword ptr [rax + rax]", P)], None, None),
+ (0x1001920, 20, "mov", [("rcx, rax", P)], "trail1", RCX),
+ (0x1001923, 20, "mov", [("rax, rdi", P)], "trail0", RAX),
+ (0x1001926, 21, "mov", [("rdi, qword ptr [rdi + 8]", P)], "cur", None), # its note is each frame's
+ (0x100192a, 22, "mov", [("qword ptr [rax + 8], rcx", P)], None, None),
+ (0x100192e, 20, "test", [("rdi, rdi", P)], None, None),
+ (0x1001931, 20, "jne", [(0x1001920, C_)], "trail2", ("text", "taken")),
+ (0x1001933, 20, "pop", [("rbp", P)], None, None),
+ (0x1001934, 26, "ret", [], None, None),
+ (0x1001935, 26, "xor", [("eax, eax", P)], None, None),
+ (0x1001937, 26, "ret", [], None, None),
+ (0x1001938, None, "endbr64", [], "out", ("text", "_init", FAINT)),
]
def frame(name, step, subject=False):
- """subject: the lens is what the scene is about, and takes rows from the source and the disassembly."""
+ """step: mid-step, the load done. subject: the lens is what the scene is about, and the band is taller."""
g = Svg()
rdi = (0x28b41070, 9) if step else (0x28b41090, 4)
# what the last three steps changed, and (mid-step) what this one has
- reg_marks = {"rax": {0: "tick"}, "rcx": {0: "tick"}}
+ reg_marks = {"rax": {0: "tick"}, "rcx": {0: "tick"}, "rdi": {0: "strike" if step else "tick"}}
lens_marks = {"tick": [0x28b410b8]}
- pointing = {0x28b410b0: ["rcx"], 0x28b41090: ["rax"] + ([] if step else ["rdi"]), 0x28b41070: ["rdi"] if step else []}
- note_marks = None
+ pins = {0x28b410b0: ["rcx"], 0x28b41090: ["rax"] + ([] if step else ["rdi"]), 0x28b41070: ["rdi"] if step else []}
if step:
- reg_marks["rdi"] = {0: "strike"}
- lens_marks.update(read=0x28b41098, land=0x28b41070)
- note_marks = {0: "read"}
- else:
- reg_marks["rdi"] = {0: "tick"}
-
- lens_h, src_rows, src_first = (432, 8, 17) if subject else (312, 12, 15)
- xs, rows, land_x = lens(g, TOP, NODES, pointing, lens_marks, lens_h, subject)
- y = TOP + lens_h + 12
- source(g, y, src_rows, SRC, src_first, 21, [20, 22], "list.c", len(SRC) - 1)
- y += TAG + 12 + src_rows * ROW + 12
- dis = list(DIS)
- dis[3] = ("note", "rdi + 8 =", [(0x28b41098, H_), (0x28b41070, H_)], ("int", 9), note_marks)
- disasm(g, y, dis[1:] if subject else dis, "reverse")
+ lens_marks["read"] = 0x28b41098
- where = registers(g, TOP, regs_at(rdi), (0x206, [("CF", 0, 0), ("PF", 1, 0), ("AF", 0, 0), ("ZF", 0, 1), ("SF", 0, 0),
- ("IF", 1, 0), ("DF", 0, 0), ("OF", 0, 0)]), reg_marks)
- stack(g, TOP + 468 + 12, STACK_ROWS)
- backtrace(g, TOP + 468 + 12 + 228 + 12, FRAMES)
+ band, src_rows, src_first, dis, words, dump_first, dump_rows = (
+ (248, 10, 18, DIS[3:14], 4, 0x28b41030, 9) if subject else (152, 8, 19, DIS, 8, 0x28b41070, 5))
+ y = TOP + band + 12
+ ys = source(g, y, src_rows, SRC, src_first, 21, [20, 22], "list.c", len(SRC) - 1)
+ yd = y + ph(src_rows) + 12
+ dis = list(dis)
+ i = [r[0] for r in dis].index(0x1001926)
+ dis[i] = dis[i][:5] + (("chain", [(0x28b41098, H_), (0x28b41070, H_)], ("int", 9), {0: "read"} if step else None),)
+ at = disasm(g, yd, dis, "reverse", 21, jump=(0x1001931, 0x1001920))
+ thread(g, ys, [(at[0x1001926], at[0x1001926] + ROW)])
- if step:
- # the one link drawn: from the register just struck to the node it now holds, in heap's ink, for this step
- yy, links = where["rdi"]
- ty = rows[0x28b41070] + (15 if subject else 12)
- gen.arrow(g, [(RX, yy + 12), (RX - 16, yy + 12), (RX - 16, ty), (land_x, ty)], HEAP, 3, r=8, hl=12, hw=10)
+ where = registers(g, y, regs_at(rdi), FLAGS, reg_marks)
+ stack(g, y + ph(17) + 12, STACK_ROWS[:words], FRAMES)
+ lens(g, TOP, band, NODES, pins, lens_marks, dump_first, dump_rows,
+ link_from=(where["rdi"], "rdi") if step else None, subject=subject)
# the scene's clock: how far through the recording, on the rule over the caption
g.rect(LX, 899, W - 2 * LX, 2, RULE)
- at = 71.5 if step else 71
- g.rect(LX, 898, (W - 2 * LX) * at / 95, 4, GOLD)
+ g.rect(LX, 898, (W - 2 * LX) * (71.5 if step else 71) / 95, 4, GOLD)
g.t(W - LX, 934, "moment %d of 95" % (72 if step else 71), S, FAINT, MONO, "end")
if step:
- gen.caption(g, [[("The load read the word at ",), ("28b4 1098", "mono"), (": the address of the next node.",)],
- [("rdi", "mono"), (" holds it now, and follows it to the node whose value is 9.",)]])
+ gen.caption(g, [[("The load read the word at ",), ("28b41098", "mono"), (": the address of the next node.",)],
+ [("rdi", "mono"), (" holds it now, and points at the node whose value is 9.",)]])
else:
gen.caption(g, [[("Stopped in ",), ("reverse", "mono"), (", about to load ",), ("head->next", "mono"), (".",)],
- [("rdi", "mono"), (" holds a node's address; the word after its value is the next node.",)]])
+ [("rdi", "mono"), (" points at a node; the word after its value is the next node.",)]])
g.save(name)
if __name__ == "__main__":
+ assert ph(8) + 12 + ph(17) == ph(17) + 12 + ph(8) == BOTTOM - TOP - 152 - 12 # lens beside
+ assert ph(10) + 12 + ph(11) == ph(17) + 12 + ph(4) == BOTTOM - TOP - 248 - 12 # lens as subject
+ assert shared([0x1001910, 0x1001937]) == 5 and shared([0x28b41070]) == 6
frame("09-context", False)
frame("10-context-step", True)
frame("11-context-lens", True, subject=True)