#!/usr/bin/env python3
"""The frame: the machine's whole context, pwndbg's way, a lens over it, and the ties between them.
python3 -B context.py # writes 12-calls-subject.svg, 13-sqlite-row.svg, 14-sqlite-page.svg (9 to 11: map.py)
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 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.
12 is the fib scene's recording (anim/zig-out/recordings/steps.ztrace), moments 752 and 753:
`fib(4)` calling `fib(2)`; its lines from the binary by addr2line.
"""
import re
import gen
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; 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):
"""Baseline of a row at y."""
return y + ROW / 2 + 0.36 * S
def ph(rows):
"""A panel's height."""
return TAG + 2 * PAD + rows * ROW
# ---- marks: the forms of `current`, `struck` and `held`. A is the first videos'; B the catalogue's now; C the
# other readings of "white, with less opacity" (mock 15 sets them side by side).
STYLE = {"current": "B", "struck": "B", "held": "B"}
WASH = mix(BRIGHT, PAGE, 0.10) # the current row: a white wash, opaque, a tenth of the way to bright
SOFT = mix(VERM, PAGE, 0.70) # a strike's paper, B
def band():
"""The paper across the current row."""
return EMBER[GOLD] if STYLE["current"] == "A" else WASH
def current_row(g, x, y, w, plaque):
"""The current mark on a row: the band across it and the plaque on its label. Returns the plaque's letters' ink."""
g.rect(x, y, w, ROW, band())
g.rect(x, y, plaque, ROW, BRIGHT if STYLE["current"] == "C" else GOLD)
return INK
def struck(g, x, y, w, h=ROW):
"""A struck value's paper (x, w: the value's, 5 out each side). Returns its digits' ink."""
st = STYLE["struck"]
if st == "A":
g.rect(x, y + 1, w, h - 2, VERM)
return INK
if st == "B":
g.rect(x, y + 1, w, h - 2, SOFT)
return BRIGHT
g.rect(x, y + 1, w, h - 2, mix(BRIGHT, PAGE, 0.18))
g.frame(x, y + 1, w, h - 2, VERM, 2)
return BRIGHT
def held(g, x, y, w, h=ROW):
"""Changed within three steps, at the value whose left is x (w wide) on the row at y."""
st = STYLE["held"]
if st == "A":
g.rect(x - 9, y + 3, 4, h - 6, VERM)
elif st == "B": # a dog-ear: the corner of the value turned down
g.path(f"M{x - 4},{y + 2} h9 l-9,9 Z", fill=VERM)
else: # a bar under it, half strength
g.rect(x - 2, y + h - 4, w + 4, 2, mix(VERM, PAGE, 0.6))
def held_cell(g, x, y, w, h, k=1):
"""`held` on a lens's cell (k: the drawing's scale)."""
st = STYLE["held"]
if st == "A":
g.rect(x, y + h - 4 * k, w, 4 * k, VERM)
elif st == "B":
g.path(f"M{x},{y} h{12 * k} l{-12 * k},{12 * k} Z", fill=VERM)
else:
g.rect(x, y + h - 3 * k, w, 3 * k, mix(VERM, PAGE, 0.6))
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):
"""A panel's frame and its one-row tag. note: a string, or runs (text, ink, underlined) for a legend. The frame
is MINIMAP wider than w: the pane's minimap strip is drawn in it, right of the content (map.py)."""
w += MINIMAP
g.rect(x, y, w, TAG, RAISED)
g.frame(x, y, w, h, DIM if focus else RULE, 2)
if focus:
g.rect(x + 8, y + 6, 12, 12, GOLD)
else:
g.frame(x + 8, y + 6, 12, 12, FAINT, 2)
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:
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
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):
return len("%x" % n) * A
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, y + ROW - 3, len(d) * A, 2, ink)
return x + len(d) * A
def link_arrow(g, x, y, ink=FAINT):
"""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):
"""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; within
4096 of 2^64, negative."""
if v >= (1 << 64) - 4096:
s = "-%d" % ((1 << 64) - v)
g.t(x, b(y), s, S, ink, MONO)
return x + len(s) * A
if v < 10:
g.t(x, b(y), str(v), S, ink, MONO)
return x + A
s = "0x%x" % v
g.t(x, b(y), s, S, ink, MONO)
x += len(s) * A
if v <= 0xffff:
g.t(x + 8, b(y), str(v), S, FAINT, MONO)
x += 8 + len(str(v)) * A
return x
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)
m = marks.get(i)
if m == "strike":
addr(g, x, y, n, struck(g, x - 5, y, w + 10), BOLD)
else:
if m == "tick":
held(g, x, y, w)
if m == "read":
g.frame(x - 6, y, w + 12, ROW, READ, 2)
addr(g, x, y, n, ink, lead=lead if i == 0 else 0)
where.append((x, w))
x += w
if named: # code: its name is what a reader reads
g.t(x + 10, b(y), link[2], S, VELLUM, MONO)
x += named
if end is None:
return where
if end[0] == "int" and links and room is not None and x + 30 + len("%x" % end[1]) * A + 24 > room:
more(g, x, y) # the value does not fit: the chain ends early, and says so
return where
x = value_arrow(g, x, y) if links else x
if marks.get("end") == "tick": # the value it holds changed within three steps
held(g, x + 2, y, len(str(end[1])) * A if end[0] == "int" else 3 * A)
if marks.get("end") == "strike" and end[0] == "int": # the value written: the softened vermilion, bold
s_ = str(end[1]) if end[1] < 10 else "0x%x" % end[1]
g.t(x, b(y), s_, S, struck(g, x - 5, y, len(s_) * A + 10), BOLD)
return where
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:
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 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, sw=3):
"""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, sw, r=8, hl=10 + 2 * (sw - 3), hw=10 + 2 * (sw - 3))
face = BOLD
by = y + 8 + size * 0.86
if names and names[0]: # names keep their side: None holds a side that was left
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)
def arcs(g, x, found, rows_y, lanes, touched=(), align=16):
"""`arc`: for each (source row, field address, target address, ink), a pointer whose target row is in this
panel: from the source row's left, along a lane at x + lanes[k], to the target row's address, head first. Going
up it leaves its row at 9 and arrives at 15 (going down, 15 and 9), so a chain shares a lane; nested spans
take inner lanes, the longest outermost. Standing ones quiet (60% toward the page); those the step touches
full. A target out of the window, touched: a stub to the panel's rule. Returns how many were not drawn."""
items = []
for src, field, tgt, ink, edge in found:
ys = rows_y[src]
yt = rows_y.get(tgt - tgt % align)
if yt is None:
if field in touched and edge is not None: # out of the window: a stub, only for the step's pointer
up = edge < ys
items.append((abs(ys - edge), ys + (9 if up else 15), edge, ink, True, True))
continue
up = yt < ys
items.append((abs(ys - yt), ys + (9 if up else 15), yt + (15 if up else 9), ink, field in touched, False))
items.sort(key=lambda it: -it[0])
taken, dropped = [[] for _ in lanes], 0
for span, y0, y1, ink, hot, stub in items:
lo, hi = min(y0, y1), max(y0, y1)
k = next((k for k in range(len(lanes)) if all(hi < a or lo > z for a, z in taken[k])), None)
if k is None:
dropped += 1
continue
taken[k].append((lo, hi))
lx = x + lanes[k]
col = ink if hot else mix(ink, PAGE, 0.4)
if stub:
gen.arrow(g, [(x + 21, y0), (lx, y0), (lx, y1)], col, 2, r=4, hl=7, hw=8)
else: # from the row's left, to the row's left: the brackets and addresses untouched
gen.arrow(g, [(x + 21, y0), (lx, y0), (lx, y1), (x + 22, y1)], col, 2, r=4, hl=7, hw=8)
return dropped
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 ---------------------------------------------------------------
QUIET_PITCH = 285 # a quiet register's cell: three to a row
def reg_rows(quiet):
"""The registers panel's rows: one a register the scene moves (and rsp, rbp, rip), a row of three the rest."""
return 17 - len(quiet) + (len(quiet) + 2) // 3
def registers(g, y, regs, flags, marks, quiet=()):
"""quiet: the registers no step of the scene changes, folded three to a row over rip: each its name and its
value in its ink, a pointer's chain cut to `more` at once (the map has it whole)."""
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, reg_rows(quiet), "registers", note=legend)
where = {}
full = [r for r in regs if r[0] not in quiet]
if quiet:
qy = y0 + (len(full) - 1) * ROW
g.rect(RX + 2, qy, CW - 4, 2, RULE)
for k, (name, links, end) in enumerate(r for r in regs if r[0] in quiet):
xx, yy = RX + 12 + (k % 3) * QUIET_PITCH, qy + (k // 3) * ROW
where[name] = yy
g.t(xx, b(yy), name, S, FAINT, MONO)
if links:
x = addr(g, xx + 48, yy, links[0][0], links[0][1])
if len(links) > 1 or end is not None:
more(g, x, yy)
else:
integer(g, xx + 48, yy, end[1])
full = full[:-1] + [None] * ((len(quiet) + 2) // 3) + full[-1:]
for i, r in enumerate(full):
if r is None:
continue
name, links, end = r
yy = y0 + i * ROW
if name == "rip":
g.t(RX + 12, b(yy), name, S, current_row(g, RX + 2, yy, CW - 4, 54), BOLD)
else:
g.t(RX + 12, b(yy), name, S, DIM, MONO)
where[name] = yy
if links:
chain(g, RX + 72, yy, links, end, marks.get(name), room=RX + CW - 12)
else:
if marks.get(name, {}).get(0) == "strike":
s_ = ("0x%x" % end[1]) if end[1] >= 10 else str(end[1])
g.t(RX + 72, b(yy), s_, S, struck(g, RX + 67, yy, len(s_) * A + 10), BOLD)
continue
integer(g, RX + 72, yy, end[1])
if marks.get(name, {}).get(0) == "tick":
held(g, RX + 72, yy, len(str(end[1])) * A)
# 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:
held(g, x + 4, yy, 2 * A)
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, mix(DIM, band(), 0.8), MONO)
x += 42
return where
def stack(g, y, rows, frames, note=None, rsp=None, roles=None, touched=(), chain_too=False, title="stack",
ink_of=None):
"""rows: (slot, pins, links, end[, marks]). frames: (name, first row, last row), newest first: the
backtrace, drawn on the words that are each frame; a first row under 0 runs above the window. The window
is the newest frame's. A frame's name is never cut for a chain: the chains on the rows it sits on end 12
before it. rsp: the slots' offsets from it are drawn (pwndbg's column). roles: {row: (what the slot is, ink)}:
a local's name, `saved rbp`, `return`, ranged right where the chain's room ends; the chain ends 12 before it.
Returns each row's y."""
y0 = panel(g, RX, y, CW, len(rows), title, note=(note or "%s words from rsp" % {6: "six", 8: "eight"}[len(rows)])
+ " · the frames they belong to")
lead = shared([r[0] for r in rows])
room = {} # a row's chain ends here, where a frame's name begins
spans = []
for i, (name, first, last) in enumerate(frames):
if first >= len(rows):
break
open_top, open_ = first < 0, last >= len(rows)
first, last = max(first, 0), min(last, len(rows) - 1)
x, ya, yb = RX + CW - 14, y0 + first * ROW + (0 if open_top else 3), y0 + (last + 1) * ROW - (0 if open_ else 3)
ny = (ya + yb) / 2 + 6 # the name's baseline, and the rows its letters cover
nx = x - 14 - tw(name, 18, "sansm")
for r in range(len(rows)):
if y0 + r * ROW < ny + 4 and y0 + (r + 1) * ROW > ny - 14:
room[r] = min(room.get(r, RX + CW - 136), nx - 12)
spans.append((i, name, x, ya, yb, ny, open_top, open_))
ys = []
roles = roles or {}
first = RX + (184 if rsp is not None else 122)
for i, (slot, pins, links, end, *marks) in enumerate(rows):
yy = y0 + i * ROW
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 (the introduction's +0x18)
off = slot - rsp
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)
g.t(first + 13 * A, b(yy), "%x" % end[1], S, FAINT, MONO)
continue
if i in roles:
text, ink = roles[i]
g.t(end_x, b(yy), text, S, ink, MONO, "end")
end_x -= len(text) * A + 12
chain(g, first, yy, [(slot, ink_of(slot) if ink_of else STACK)] + links, end, marks[0] if marks else None,
room=end_x, lead=lead)
# the arcs: a word holding the address of a slot in the window. The frame chain (a saved rbp) is the spans'
# already, and is drawn only when the step touches it.
slots = {r[0]: ys[i] for i, r in enumerate(rows)}
found = []
for i, (slot, pins, links, end, *marks) in enumerate(rows):
if marks and marks[0].get("free") or not links:
continue
v = links[0][0]
is_chain = roles.get(i, ("",))[0] == "saved rbp"
if links[0][1] == STACK and (not is_chain or slot in touched or chain_too):
edge = y + TAG + 1 if v < rows[0][0] else ys[-1] + ROW + PAD - 1
found.append((slot, slot, v, STACK, edge))
arcs(g, RX, [(s0, f, t, ink, e) for s0, f, t, ink, e in found if t in slots or f in touched], slots, (4, 10), touched,
align=8)
for i, name, x, ya, yb, ny, open_top, open_ in spans:
ink = GOLD if i == 0 else RULE
g.rect(x - 1, ya, 2, yb - ya, ink)
if not open_top:
g.rect(x - 7, ya, 8, 2, ink)
if not open_:
g.rect(x - 7, yb - 2, 8, 2, ink)
g.t(x - 14, ny, name, 18, BRIGHT if i == 0 else DIM, "sansm", "end")
return ys
# ---- the program column -------------------------------------------------------------
C_WORDS = {"struct", "long", "static", "return", "while", "for", "int", "char", "sizeof", "if", "else", "void", "NULL",
"__attribute__", "noinline", "const", "unsigned", "do", "elif", "defined"}
def c_line(g, x, y, text, limit):
"""One line of C in the four inks. Cut, with a faint mark, where the panel ends."""
cut = len(text) > limit
text = text[:limit - 1] if cut else text
if text.lstrip().startswith("//"):
g.t(x, b(y), text, S, COMMENT, ITAL)
return
for m in re.finditer(r'/\*.*?(\*/|$)|"[^"]*"?|#\w+|<[\w.]+>|\w+|\s+|.', text):
s = m.group()
if not s.strip():
continue
if s.startswith("/*"): # a comment, to the line's end or its close
g.t(x + m.start() * A, b(y), s, S, COMMENT, ITAL)
continue
ink, face = VELLUM, MONO
if s in C_WORDS or s.startswith("#"):
ink, face = KW, BOLD
elif s[0] == '"' or s[0].isdigit() or (s[0] == "<" and len(s) > 2):
ink = LIT
g.t(x + m.start() * A, b(y), s, S, ink, face)
if cut:
g.t(x + (limit - 1) * A, b(y), "…", S, FAINT, MONO)
def wide(total):
"""How much wider than three characters the program's largest line number is: the same in every window."""
return max(len(str(total)) - 3, 0) * A
def source(g, y, rows, lines, first, cur, trail, name, total, waiting=None):
"""Returns the y of the current line's row. Numbers as wide as the file's last: the text moves by the extra.
waiting: the pc is in code with no source; cur is the line whose call it is under, ringed, and the tag says
where the pc is."""
w = wide(total)
y0 = panel(g, LX, y, CW, rows, name, note=waiting or f"lines {first} to {min(first + rows - 1, total)} of {total}")
for i in range(rows):
n = first + i
yy = y0 + i * ROW
if n == cur and waiting:
g.frame(LX + 2, yy, 50 + w, ROW, VELLUM, 2)
g.t(LX + 46 + w, b(yy), str(n), S, VELLUM, BOLD, "end")
elif n == cur:
g.t(LX + 46 + w, b(yy), str(n), S, current_row(g, LX + 2, yy, CW - 4, 50 + w), BOLD, "end")
else:
if n in trail:
g.rect(LX + 2, yy + 1, 4, ROW - 2, TRAIL[min(trail.index(n), 2)])
g.t(LX + 46 + w, b(yy), str(n), S, FAINT, MONO, "end")
c_line(g, LX + 64 + w, yy, lines[n - 1], (CW - 64 - w - 12) // A)
return y0 + (cur - first) * ROW
DX_ADDR, DX_LINE, DX_MN, DX_OPS, DX_NOTE = 40, 134, 180, 264, 564
SIZES = {"byte": 1, "word": 2, "dword": 4, "qword": 8, "tbyte": 10, "xmmword": 16, "ymmword": 32, "zmmword": 64}
IMPLIED = {"push", "pop", "call", "jmp", "lea", "nop", "endbr64"} # the width is the mnemonic's, or nothing is touched
def reg_width(r):
"""The bytes a register names, or None for what is not one (a segment, a number)."""
m = re.fullmatch(r"([xyz])mm\d+", r) or re.fullmatch(r"r(\d+)([dwb]?)", r)
if m and m.re.pattern.startswith("(["):
return {"x": 16, "y": 32, "z": 64}[m.group(1)]
if m:
return {"": 8, "d": 4, "w": 2, "b": 1}[m.group(2)]
for n, pat in ((8, r"r([abcd]x|[sd]i|[sb]p|ip)"), (4, r"e([abcd]x|[sd]i|[sb]p|ip)"), (2, r"[abcd]x|[sd]i|[sb]p"),
(1, r"[abcd][lh]|[sd]il|[sb]pl")):
if re.fullmatch(pat, r):
return n
return None
def width(g, x, y, n):
"""`width`: an access's size as byte cells after the operand it is the size of: 5 by 10, 7 apart, 3 after
the bracket, in dim; what follows the operand goes on 4 after the last. Returns where it goes on."""
for i in range(min(n, 8)):
g.rect(x + 3 + i * 7, y + 9, 5, 10, DIM)
end = x + 3 + min(n, 8) * 7 - 2
if n > 8: # wider than a word: the count after the cells
g.t(end + 4, b(y), str(n), S, FAINT, MONO)
end += 4 + len(str(n)) * A
return end + 4
def operands(g, x, y, mn, s, ink, sizes=False):
"""Operands as the disassembler writes them, less the size word (`qword ptr `). Where no register of the
same instruction has the access's size, a `width` after the bracket says it. sizes: draw them as written
(the mock's 'before'). Returns where the row's text ends."""
m = re.search(r"\b(%s) ptr " % "|".join(SIZES), s)
if sizes or not m:
g.t(x, b(y), s, S, FAINT if mn in ("nop", "endbr64") else ink, MONO)
return x + len(s) * A
n, s = SIZES[m.group(1)], s[:m.start()] + s[m.end():]
if mn in ("nop", "endbr64"): # padding: nothing is read or written
g.t(x, b(y), s, S, FAINT, MONO)
return x + len(s) * A
outside = re.sub(r"\[.*?\]", "", s)
if mn in IMPLIED or n in [reg_width(t) for t in re.findall(r"[a-z][a-z0-9]*", outside)]:
g.t(x, b(y), s, S, ink, MONO)
return x + len(s) * A
cut = s.index("]") + 1
g.t(x, b(y), s[:cut], S, ink, MONO)
x = width(g, x + cut * A, y, n)
g.t(x, b(y), s[cut:], S, ink, MONO)
return x + len(s[cut:]) * A
def disasm(g, y, rows, func, cur_line, jump=None, w=0, sizes=False):
"""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) | wait (a call
whose callee is open under it, in a descent) | None.
note, the row's annotation: ("chain", links, end, marks) | ("set", register, links, end) | ("text", s) |
("runs", [(s, ink)]).
jump: (from, to): a jump that was taken, drawn in the lane. w: how much wider than three characters the
program's line numbers are; every column right of the line's moves by it.
Returns each address's row y."""
y0 = panel(g, LX, y, CW, len(rows), "disassembly", note=func)
where = insn_rows(g, y0, rows, cur_line, w, sizes=sizes)
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
def insn_rows(g, y0, rows, cur_line, w=0, lead=None, sizes=False):
"""`insn` rows from y0, a row each. Addresses wider than seven digits (a library's, 7ffff7d10fc5) move every
column right of theirs by the extra, for the rows of this window only."""
lead = shared([r[0] for r in rows if r[4] != "out"]) if lead is None else lead
w += max(max(len("%x" % r[0]) for r in rows) - 7, 0) * A
where, last_line = {}, None
for i, (a, line, mn, ops, st, note) in enumerate(rows):
yy = y0 + i * ROW
where[a] = yy
dim = st in ("out", "skip") # skip: on the page, not on the path this run takes
if st in ("out", "other_first"): # a function ends: a rule, and the next one's name
g.rect(LX + 2, yy, CW - 4, 2, RULE)
if st == "cur":
g.path(f"M{LX + 20},{yy + 12} l-10,-6 v12 Z", fill=current_row(g, LX + 2, yy, CW - 4, 24))
elif st == "wait": # it called, and waits: the plaque's place ringed, as a waiting call node
g.frame(LX + 2, yy, 24, ROW, VELLUM, 2)
g.path(f"M{LX + 19},{yy + 12} l-8,-5 v10 Z", fill=VELLUM)
elif st and st.startswith("trail"):
g.rect(LX + 2, yy + 1, 4, ROW - 2, TRAIL[int(st[-1])])
elif st == "pass": # a stub's jump, passed through on the way down
g.rect(LX + 2, yy + 1, 4, ROW - 2, TRAIL[1])
addr(g, LX + DX_ADDR, yy, a, mix(CODE, PAGE, 0.6) if dim else CODE, lead=0 if dim else lead)
if line is not None and line != last_line and not dim: # the line this run was compiled from
on = line == cur_line
g.t(LX + DX_LINE + 3 * A + w, b(yy), str(line), S, GOLD if on else FAINT, BOLD if on else MONO, "end")
last_line = line
g.t(LX + DX_MN + w, b(yy), mn, S, FAINT if dim or mn in ("nop", "endbr64") else KW,
MONO if dim or mn in ("nop", "endbr64") else BOLD)
x = LX + DX_OPS + w
for part, ink in ops:
if isinstance(part, int):
x = addr(g, x, yy, part, ink)
elif isinstance(part, tuple): # a target and its name: `401070 open@plt`
x = addr(g, x, yy, part[0], ink)
g.t(x + A, b(yy), part[1], S, VELLUM, MONO)
x += A + len(part[1]) * A
else:
x = operands(g, x, yy, mn, part, FAINT if dim else ink, sizes)
if not note:
continue
x = max(LX + DX_NOTE + w, x + A) # operands are never cut where the row has room
if note[0] == "text":
g.t(x, b(yy), note[1], S, note[2] if len(note) > 2 else DIM, MONO)
elif note[0] == "runs": # a line of the row's own: words, values, chips
for s_, ink in note[1]:
if isinstance(s_, int):
x = addr(g, x, yy, s_, ink)
elif ink == "arrow": # `points`
x = link_arrow(g, x, yy)
elif ink == "chip": # a flag the instruction set, as rip's row draws it
g.rect(x, yy + 2, 32, 20, RAISED)
g.t(x + 16, b(yy), s_, S, BRIGHT, BOLD, "middle")
x += 32 + 6
else:
g.t(x, b(yy), s_, S, ink, MONO)
x += len(s_) * A
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))
return where
def descent(g, y, windows, note=None, w=0, sizes=False):
"""`disasm` as a descent: a window of code a call deep, the caller's first, each callee's under the row that
called it. windows: (name, about, rows) for code, rows as disasm's; ("kernel", about, lines) last, lines
being runs [(s, ink)] on vellum. A window after the first opens with a head row: a rule, the call lane
arriving from the row that called (a `wait` row) or jumped (the row before the head), the name, what it is.
Returns {address: y}, and each head's y under its name."""
n = sum(len(wn[2]) for wn in windows) + len(windows) - 1
y0 = panel(g, LX, y, CW, n, "disassembly", note=note)
yy, where, came = y0, {}, None
for k, (name, about, rows) in enumerate(windows):
if k:
kern = name == "kernel"
if kern: # solid vellum is the kernel
g.rect(LX + 2, yy, CW - 4, (len(rows) + 1) * ROW, gen.KERNEL)
g.rect(LX + 2, yy, CW - 4, 2, gen.KERNEL_RULE if kern else RULE)
g.t(LX + DX_ADDR, b(yy), name if not kern else "the kernel", 18, PAGE if kern else VELLUM, "sansm")
g.t(LX + CW - 12, b(yy), about, 18, gen.KERNEL_DIM if kern else FAINT, "sans", "end")
if came is not None and not kern: # the call lane: down from the row that went, into the head
gen.arrow(g, [(LX + 14, came), (LX + 14, yy + 12), (LX + 34, yy + 12)], VELLUM, 2, r=4, hl=7, hw=8)
elif came is not None: # the crossing: down from the `syscall` row onto the vellum, its head in ink
g.rect(LX + 12.5, came, 3, yy - came, VELLUM)
g.path(f"M{LX + 14},{yy + 14} l-6,-10 h12 Z", fill=PAGE)
where[name] = yy
yy += ROW
if kern:
for i, runs in enumerate(rows):
x = LX + DX_ADDR
for s_, ink in runs:
if ink == "struck":
g.rect(x - 5, yy + i * ROW + 1, len(s_) * A + 10, ROW - 2, SOFT)
g.t(x, b(yy + i * ROW), s_, S, BRIGHT, BOLD)
else:
g.t(x, b(yy + i * ROW), s_, S, ink, MONO)
x += len(s_) * A
yy += len(rows) * ROW
continue
at = insn_rows(g, yy, rows, None, w, sizes=sizes)
where.update(at)
went = [r for r in rows if r[4] in ("wait", "pass", "cur")]
came = (at[went[-1][0]] + (ROW if went[-1][4] == "wait" else 18)) if went else None
yy += len(rows) * ROW
return where
def thread(g, ys, spans, ink=GOLD, sw=3):
"""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.
Waiting (the pc is in code with no source, under this line's call): primary, 2."""
x = LX - 10
bracket(g, x, ys + 2, ys + ROW - 2, ink, sw, 7)
for ya, yb in spans:
bracket(g, x, ya + 2, yb - 2, ink, sw, 7)
g.rect(x - sw / 2, ys + 2, sw, spans[-1][1] - 2 - ys - 2, ink)
# ---- the lens: a list, and beside it the bytes it is drawn from -------------------------
def fields(g, y, h, about, base, length, flist, mem, region, region_of, marks=(), title="its bytes", x=None,
framed=(), bare=False, rows_shown=None, more_rows=True, touched=(), withhold=None, hot=False, changed=(),
held_at=()):
"""`hexdump` by `fields`: the region a scene names, read by the fields it gives it, in the band's view.
flist: (at, len, reads, big, mark) with reads in number | pointer | text | bytes. mem: {address: byte} of what
the stop shown saw (or the kernel took); a byte not in it is unread. marks: the field marks framed as read.
Rows that hold no field are one `more` row and their count. The bytes begin 12 after the widest address.
reads `malloc`: the allocator's size word, loose, read as a note. framed: (at, len) drawn with `attention`'s
bright frame (a loupe's target). bare: no tag (a loupe draws its own). rows_shown: the rows to show, when the
window is not every row that holds a field. Returns {row address: y}."""
X = RX if x is None else x
if not bare:
tag(g, X, y, CW, h, title)
g.t(X + 28 + tw(title, 20, "sansm") + 12, y + 18, about, 18, FAINT, "sans")
total = (length + 15) // 16
holds = lambda r: any(base + at < base + 16 * (r + 1) and base + at + n > base + 16 * r for at, n, *_ in flist)
shown = rows_shown if rows_shown is not None else [r for r in range(total) if holds(r)]
ys = {}
digits = max(len("%x" % (base + 16 * r)) for r in shown)
shift = max(34 + digits * A + 12 - 132, 0)
found = []
bx = lambda i: X + 132 + shift + i * 30 + (12 if i >= 8 else 0)
lead = shared([base + 16 * r for r in shown]) if len(shown) > 1 else 0
yy, last = y + TAG + PAD, None
for r in shown:
if last is not None and r > last + 1: # the rows left out: one row, and how many
more(g, X + 34 - 6, yy)
g.t(X + 34 + 30 + 36, b(yy), "%d rows" % (r - last - 1), S, FAINT, MONO)
yy += ROW
last = r
a0 = base + 16 * r
ys[a0] = yy
bracket(g, X + 24, yy + 3, yy + ROW - 3, mix(region, PAGE, 0.6))
addr(g, X + 34, yy, a0, region, lead=lead)
runs, i = [], 0
while i < 16 and a0 + i < base + length:
f = next((f for f in flist if base + f[0] <= a0 + i < base + f[0] + f[1]), None)
if f:
n = min(base + f[0] + f[1] - (a0 + i), 16 - i)
else:
n = min([base + o[0] - a0 for o in flist if a0 + i < base + o[0] < a0 + 16] + [16, base + length - a0]) - i
runs.append((i, n, f))
i += n
x = X + 640 + shift # the reading: a list, a character apart
for i0, n, f in runs:
vals = [mem.get(a0 + k) for k in range(i0, i0 + n)]
reads = f[2] if f else "loose"
x0, x1 = bx(i0) - 4, bx(i0 + n - 1) + 28
if f and reads != "malloc":
g.rect(x0, yy + 1, x1 - x0, ROW - 2, RAISED)
if f[4] is not None and f[4] in marks:
g.frame(x0 - 3, yy - 1, x1 - x0 + 6, ROW + 2, READ, 2)
known = None not in vals
word = 0
if known:
order = vals[::-1] if not (f and f[3]) else vals
for v in order:
word = word << 8 | v
for fa, fl in framed: # the target: framed bright, as attention
if base + fa < a0 + i0 + n and base + fa + fl > a0 + i0:
g.frame(x0 - 3, yy - 1, x1 - x0 + 6, ROW + 2, BRIGHT, 2)
ink = {"number": VELLUM, "bytes": VELLUM, "text": LIT, "loose": DIM, "malloc": DIM, "size": VELLUM,
"protected": VELLUM, "pointer": (region_of(word) or VELLUM) if known else VELLUM}[reads]
nz = [k for k, v in enumerate(vals) if v]
hit = [k for k in range(n) if a0 + i0 + k in changed]
if hit: # struck: the bytes whose value changed, first to last, in the run
g.rect(bx(i0 + hit[0]) - 5, yy + 1, bx(i0 + hit[-1]) - bx(i0 + hit[0]) + 34, ROW - 2, SOFT)
if any(a0 + i0 + k in held_at for k in range(n)):
held(g, bx(i0 + min(k for k in range(n) if a0 + i0 + k in held_at)), yy, 24)
for k, v in enumerate(vals):
xx = bx(i0 + k)
if hit and hit[0] <= k <= hit[-1] and v is not None:
g.t(xx, b(yy), "%02x" % v, S, BRIGHT, BOLD)
continue
if v is None: # not read at this stop: two dots, on the field's paper
g.rect(xx + 5, yy + 11, 4, 4, FAINT)
g.rect(xx + 15, yy + 11, 4, 4, FAINT)
continue
padded = reads in ("number", "pointer", "size", "protected") and nz and (k < nz[0] if f[3] else k > nz[-1])
g.t(xx, b(yy), "%02x" % v, S, mix(ink, PAGE, 0.45) if padded else ink, MONO)
if known and f and len(f) > 5 and reads in ("bytes", "loose"): # a field the scene names, left to the eye
g.t(x, b(yy) - 1, f[5], 18, FAINT, "sans")
x += tw(f[5], 18, "sans") + A
if not known or reads in ("bytes", "loose"):
continue
if reads == "size": # a chunk's size word: the size, and its three low bits as flags
s_ = "0x%x" % (word & ~7)
g.t(x, b(yy), s_, S, VELLUM, MONO)
x += (len(s_) + 1) * A
for bit, letter in ((2, "A"), (1, "M"), (0, "P")):
if word >> bit & 1: # set: on a chip, as rip's flags; clear: lower case, dim
g.rect(x - 4, yy + 2, 20, 20, RAISED)
g.t(x, b(yy), letter, S, BRIGHT, BOLD)
else:
g.t(x, b(yy), letter.lower(), S, DIM, MONO)
x += 18
x += 6
if len(f) > 5:
g.t(x, b(yy) - 1, f[5], 18, FAINT, "sans")
x += tw(f[5], 18, "sans") + A
continue
if reads == "protected": # safe-linking: the bytes are the pointer xor its own address >> 12
fa = a0 + i0
ptr = word ^ (fa >> 12)
if ptr and base <= ptr < base + length:
found.append((a0, fa, ptr, region_of(ptr) or VELLUM, None))
if ptr:
x = addr(g, link_arrow(g, x, yy), yy, ptr, region_of(ptr) or VELLUM) + A
else:
g.t(x, b(yy), "NULL", S, DIM, MONO)
x += 5 * A
s_ = "^ %x" % (fa >> 12)
g.t(x, b(yy), s_, S, FAINT, MONO)
x += (len(s_) + 1) * A
continue
if reads == "malloc": # the allocator's own: the size word of the chunk after it
note = "malloc's: a chunk of %d" % (word & ~7) if word < 0x10000 else "malloc's: the top chunk"
g.t(x, b(yy) - 1, note, 18, FAINT, "sans")
x += tw(note, 18, "sans") + A
continue
if reads == "pointer" and word and base <= word < base + length: # a row of this panel: an arc too
found.append((a0, a0 + i0, word, region_of(word) or VELLUM, None))
if reads == "pointer":
if word == 0:
s_, sink = "NULL", DIM
else:
x = addr(g, link_arrow(g, x, yy), yy, word, region_of(word) or VELLUM) + A
continue
elif reads == "number":
s_, sink = str(word), VELLUM
else:
s_, sink = '"' + bytes(vals).split(b"\0")[0].decode("latin1") + '"', LIT
if x + len(s_) * A > X + CW - 12:
s_ = s_[:max(int((X + CW - 12 - x) // A) - 1, 0)] + "…"
g.t(x, b(yy), s_, S, sink, MONO)
x += (len(s_) + 1) * A
if f and len(f) > 5: # what the scene says the number is
g.t(x, b(yy) - 1, f[5], 18, FAINT, "sans")
x += tw(f[5], 18, "sans") + A
yy += ROW
if more_rows and shown and shown[-1] < total - 1: # the rows after the last field: one row, and how many
more(g, X + 34 - 6, yy)
g.t(X + 34 + 30 + 36, b(yy), "%d rows" % (total - 1 - shown[-1]), S, FAINT, MONO)
top, foot = y + TAG + 1, yy + (ROW if more_rows and shown and shown[-1] < total - 1 else 0) + PAD - 1
found = [(s0, f, t, ink, top if t < base + 16 * shown[0] else foot) for s0, f, t, ink, _ in found
if not (withhold and withhold[0] <= s0 < withhold[1] and withhold[0] <= t < withhold[1])] # a loupe has them
arcs(g, X, found, ys, (4, 10, 16), {f for _, f, _, _, _ in found} if hot else touched) # a loupe: all at full ink
return ys
def calls_log(g, y, h, calls):
"""`syscalls`'s drawing: the calls so far, as strace writes them, oldest on top, the newest last; the kernel's
own side is under the `syscall` row while a call is made (`descent`), not here. calls: runs [(s, ink)] a row,
oldest first; the newest's result carries the turned corner."""
rows = (h - TAG - 2 * PAD) // ROW
note = "oldest on top · newest at the bottom" + (" · %d more above" % (len(calls) - rows) if len(calls) > rows else "")
y0 = panel(g, LX, y, CW, rows, "system calls", focus=True, note=note)
shown = calls[-rows:]
for i, runs in enumerate(shown):
yy, x = y0 + i * ROW, LX + 12
for s_, ink in runs:
if ink == "held":
held(g, x, yy, len(s_) * A)
ink = VELLUM
g.t(x, b(yy), s_, S, ink, BOLD if x == LX + 12 else MONO)
x += len(s_) * A
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:
held(g, x0 + 4, y, x1 - x0 - 8)
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, hv, nodes, pins, marks, first, nrows, link_from=None, subject=False, dw=None, k=1, view_rows=None,
ties=True):
"""The band: the list drawn, over the program column, and the heap bytes it is drawn from, over the state
column; two panels, h and hv high, the gutter between them the ties'.
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.
On the 4K stage the drawing is dw wide and drawn k times the size (2), and the view is drawn by `fields`, whose
rows (view_rows: {row address: y}) the projection starts from."""
dw = dw or CW
tag(g, LX, y, dw, h, "the list", focus=True)
last = first + (nrows - 1) * 16
rows = view_rows or {}
if view_rows is None:
tag(g, RX, y, CW, hv, "its bytes",
note=[("value", VELLUM, False), ("next", HEAP, False), ("malloc's", DIM, False), ("never read", FAINT, False)])
g.t(RX + 28 + 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])
for i in range(nrows if view_rows is None else 0):
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, centred between its lanes
NW, NH, GAP, VS, LS = [v * k for v in ((124, 72, 22, 45, 25) if subject else (116, 44, 28, 25, 20))]
VW = NW - 48 * k # the value's half; the pointer's is 48
tie_w = (3, 2) if k == 1 else (4, 3) # a link, a projection: on the 4K stage, 2 and 1.5 pixels at 1080p
x0 = LX + (dw - len(nodes) * NW - (len(nodes) - 1) * GAP) / 2
lane_top, lane_bot = y + TAG + 4, y + h - 8
block = LS * 1.2 + 4 + NH + LS + 10 + 8 # address, node, the pins' stub and names
ly = y + TAG + (16 * k if not subject else round((h - TAG - block) / 2)) # 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)
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 * k, ny - 2 * k, NW - VW + 4 * k, NH + 4 * k, READ, 2 * k)
if a + 8 in marks.get("tick", ()):
held_cell(g, x + VW, ny, NW - VW, NH, k)
cx, cy = x + VW + (NW - VW) / 2, ny + NH / 2
if nx:
g.rect(cx - 5 * k, cy - 5 * k, 10 * k, 10 * k, HEAP)
gen.arrow(g, [(cx + 8 * k, cy), (xs[nx] - 3 * k, cy)], HEAP, 3 * k, hl=12 * k, hw=10 * k)
else:
g.path(f"M{x + VW + 10 * k},{ny + NH - 8 * k} L{x + NW - 10 * k},{ny + 8 * k}", DIM, 2 * k)
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
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, sw=tie_w[0])
# the projection: the bytes a step read, and the part of the drawing that is those bytes (the map draws none)
if marks.get("read") and ties:
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, tie_w[1])
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 ---------------------------------------
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):
return [
("rax", [(0x28b41090, H_)], ("int", 4)),
("rbx", [], ("int", 0)),
("rcx", [(0x28b410b0, H_)], ("int", 1)),
("rdx", [], ("int", 0)),
("rsi", [(0x28b410c0, H_)], ("int", 0)),
("rdi", [(rdi[0], H_)], ("int", rdi[1])),
("rbp", RBP, ("int", 0)),
("rsp", RBP, ("int", 0)),
("r8", [(0x7f2ba3019ac0, D_)], ("int", 0)),
("r9", [], ("int", 0x20)),
("r10", [], ("int", 0x10)),
("r11", [(0x7f2ba3019ac8, D_), (0x28b410c0, H_)], ("int", 0)),
("r12", ARGV, ("str", "zig-out/targets/list")),
("r13", [], ("int", 1)),
("r14", [(0x7f2ba32ac000, D_), (0x7f2ba32ad3c0, D_)], ("int", 0)),
("r15", [(0x10029c0, VELLUM)], ("int", 1)),
("rip", [(0x1001926, C_, "reverse+22")], None),
]
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),
(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", 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
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)),
]
# The splits with a lens: the drawing's and its view's heights, then source lines, instructions and stack slots.
BESIDE = dict(band=152, view=152, src=8, dis=17, words=8, dump=5)
SUBJECT = dict(band=296, view=200, src=10, dis=9, words=6, dump=7)
def clock(g, moment, total):
"""The scene's clock: how far through the recording, on the rule over the caption. Still through a step."""
g.rect(LX, 899, W - 2 * LX, 2, RULE)
g.rect(LX, 898, (W - 2 * LX) * moment / total, 4, GOLD)
g.t(W - LX, 934, "moment %d of %d" % (moment, total), S, FAINT, MONO, "end")
def frame(name, step, subject=False):
"""step: mid-step, the load done. subject: the lens is what the scene is about, and the band is taller."""
g = Svg()
sp = SUBJECT if subject else BESIDE
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"}, "rdi": {0: "strike" if step else "tick"}}
lens_marks = {"tick": [0x28b410b8]}
# names keep their side: rax stays left of its stub when rdi goes, and rdi takes the free side where it lands
pins = {0x28b410b0: ["rcx"], 0x28b41090: ["rax"] + ([] if step else ["rdi"]), 0x28b41070: ["rdi"] if step else []}
if step:
lens_marks["read"] = 0x28b41098
k = [r[0] for r in DIS].index(0x1001926)
half = sp["dis"] // 2 # the pc's row, and as many above as below
dis = list(DIS[k - half:k + half + 1])
dump_first = 0x28b41050 if subject else 0x28b41070
y = TOP + sp["band"] + 12
ys = source(g, y, sp["src"], SRC, 18 if subject else 19, 21, [20, 22], "list.c", len(SRC) - 1)
yd = y + ph(sp["src"]) + 12
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)])
yr = TOP + sp["view"] + 12
where = registers(g, yr, regs_at(rdi), FLAGS, reg_marks)
stack(g, yr + ph(17) + 12, STACK_ROWS[:sp["words"]], FRAMES)
lens(g, TOP, sp["band"], sp["view"], NODES, pins, lens_marks, dump_first, sp["dump"],
link_from=(where["rdi"], "rdi") if step else None, subject=subject)
clock(g, 71, 95) # mid-step the clock has not moved: it moves when the mark has landed
if step:
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"), (" points at a node; the word after its value is the next node.",)]])
g.save(name)
# ---- the calls lens: a tree of every call, and the backtrace it is a view of -------------
def fib_calls(n):
"""Every call of fib(n), in the order they are made: (argument, parent index, level, result)."""
out = []
def call(k, parent, level):
i = len(out)
out.append([k, parent, level, None])
out[i][3] = k if k < 2 else call(k - 1, i, level + 1) + call(k - 2, i, level + 1)
return out[i][3]
call(n, None, 0)
return out
def tree_x(calls):
"""In leaf slots: leaves in call order, a parent over the middle of its children."""
kids = {i: [j for j, c in enumerate(calls) if c[1] == i] for i in range(len(calls))}
xs, leaf = {}, [0]
def place(i):
if not kids[i]:
xs[i] = leaf[0]
leaf[0] += 1
else:
for j in kids[i]:
place(j)
xs[i] = (xs[kids[i][0]] + xs[kids[i][-1]]) / 2
place(0)
return xs, leaf[0]
def calls(g, y, h, tree, made, caller, project_from=None):
"""The drawing: tree is fib_calls(); made: how many calls have been made (the last is running).
project_from: the y of the stack row whose return address the newest node is drawn from, mid-step.
Returns the newest node's centre."""
tag(g, LX, y, CW, h, "calls of fib", focus=True, note="each call a node · its result on its shoulder")
D, LEVEL, BADGE = 48, 46, 30
xs, leaves = tree_x(tree)
left, right = LX + 44, LX + CW - 12 - 48 # the last leaf's badge stays inside
pitch = (right - left) / (leaves - 1)
top = y + TAG + 48
at = lambda i: (left + xs[i] * pitch, top + tree[i][2] * LEVEL)
newest = made - 1
waiting = set()
p = tree[newest][1]
while p is not None:
waiting.add(p)
p = tree[p][1]
# the caller, at the drawing's left on the root's level, clear of the tree: waiting, with an edge into the root
rx, ry = at(0)
bx = LX + 20
g.path(f"M{bx + 64},{ry} H{rx - D / 2}", VELLUM, 3)
g.rect(bx, ry - 14, 64, 28, PAGE)
g.frame(bx, ry - 14, 64, 28, VELLUM, 3)
g.t(bx + 32, b(ry - 12), caller, S, VELLUM, MONO, "middle")
# edges under the nodes: the waiting path in primary
for i in range(1, made):
(px, py), (cx, cy) = at(tree[i][1]), at(i)
live = i in waiting or i == newest
g.line(px, py, cx, cy, VELLUM if live else RULE, 3)
for i in range(made):
cx, cy = at(i)
k, _, _, result = tree[i]
if i == newest:
g.circle(cx, cy, D / 2, GOLD)
g.t(cx, cy + 0.36 * 25, str(k), 25, INK, BOLD, "middle")
elif i in waiting:
g.circle(cx, cy, D / 2 - 1.5, PAGE, VELLUM, 3)
g.t(cx, cy + 0.36 * 25, str(k), 25, VELLUM, MONO, "middle")
else:
g.circle(cx, cy, D / 2, RAISED)
g.t(cx, cy + 0.36 * 25, str(k), 25, VELLUM, MONO, "middle")
g.rect(cx + 12, cy - 42, BADGE, BADGE, PAGE)
g.frame(cx + 12, cy - 42, BADGE, BADGE, FAINT, 2)
g.t(cx + 12 + BADGE / 2, cy - 42 + BADGE / 2 + 0.36 * 25, str(result), 25, VELLUM, MONO, "middle")
cx, cy = at(newest)
if project_from is not None: # the frame's return address is the node: a projection, from below
lane_bot = y + h - 8
bracket_y = cy + D / 2 + 5
gen.arrow(g, [(RX + 3, project_from + 12), (LANE_LINK, project_from + 12), (LANE_LINK, lane_bot),
(cx, lane_bot), (cx, bracket_y + 3)], VERM, 2, r=6, head=False)
g.rect(cx - D / 2, bracket_y, D, 3, VERM)
g.rect(cx - D / 2, bracket_y - 5, 3, 8, VERM)
g.rect(cx + D / 2 - 3, bracket_y - 5, 3, 8, VERM)
bracket(g, RX + 4, project_from + 2, project_from + ROW - 2, VERM, 3, 5)
return cx, cy
def backtrace(g, y, h, frames, x=RX, note="the calls waiting · newest at the bottom", focus=False):
"""The call chain as rows, newest at the bottom (a call goes down): the view of the calls, or a lens's drawing
(x = LX). frames: (name, args, file, line), newest first, as numbered; file None where the recording does not
know it. More frames than rows: the oldest go from the top, counted."""
rows = (h - TAG - 2 * PAD) // ROW
if len(frames) > rows:
note += " · %d more above" % (len(frames) - rows)
y0 = panel(g, x, y, CW, rows, "backtrace", focus=focus, note=note)
shown = frames[:rows]
for i, (name, args, file, line) in enumerate(shown):
yy = y0 + (len(shown) - 1 - i) * ROW + (rows - len(shown)) * ROW
if i == 0:
g.t(x + 12, b(yy), "#0", S, current_row(g, x + 2, yy, CW - 4, 40), BOLD)
else:
g.t(x + 12, b(yy), "#%d" % i, S, FAINT, MONO)
g.t(x + 60, b(yy), name, S, VELLUM, MONO)
if args:
g.t(x + 384, b(yy), args, S, VELLUM, MONO)
if file:
g.t(x + CW - 12, b(yy), "%s:%d" % (file, line), S, DIM, MONO, "end")
# ---- the data: moments 752 and 753 of the fib scene (anim/zig-out/recordings/steps.ztrace) -----
FIB_SRC = open(__file__.replace("context.py", "fib.c")).read().split("\n")
FIB_RBP = [(0x7fffffffeda0, S_), (0x7fffffffedd0, S_), (0x7fffffffedf0, S_), (0x7fffffffee20, S_)]
FIB_ARGV = [(0x7fffffffee38, S_), (0x7fffffffefe8, S_)]
FIB_REGS = [
("rax", [], ("int", 2)),
("rbx", FIB_ARGV, ("str", "./steps")),
("rcx", [], ("int", 1)),
("rdx", [(0x7fffffffee48, S_)], ("int", 0)),
("rsi", FIB_ARGV, ("str", "./steps")),
("rdi", [], ("int", 2)),
("rbp", FIB_RBP, ("int", 0)),
("rsp", [(0x7fffffffed78, S_), (0x10133ab, C_, "fib+59")], None),
("r8", [], ("int", 0)),
("r9", [], ("int", 0x800000)),
("r10", [], ("int", 0x800000)),
("r11", [], ("int", 0x346)),
("r12", [(0x7fffffffee48, S_)], ("int", 0)),
("r13", [], ("int", 0)),
("r14", [(0x10133d0, C_, "main+0")], None),
("r15", [], ("int", 1)),
("rip", [(0x10133a6, C_, "fib+54")], None),
]
FIB_FLAGS = [("CF", 0, 0), ("PF", 0, 0), ("AF", 0, 0), ("ZF", 0, 0), ("SF", 0, 0), ("IF", 1, 0), ("DF", 0, 0), ("OF", 0, 0)]
FIB_STACK = [ # the window from rsp: the new frame's return address, then fib(4)'s words down to its saved rbp
(0x7fffffffed78, ["rsp"], [(0x10133ab, C_, "fib+59")], None, {1: "strike"}),
(0x7fffffffed80, [], [], ("int", 0)),
(0x7fffffffed88, [], [], ("int", 2), {"end": "tick"}),
(0x7fffffffed90, [], [], ("int", 4)),
(0x7fffffffed98, [], [(0x7ffff7ffd000, C_, "vdso+0")], None),
(0x7fffffffeda0, ["rbp"], FIB_RBP[1:], ("int", 0)),
]
FIB_FRAMES = [("fib(2)", 0, 0), ("fib(4)", 1, 9)]
FIB_DIS = [ # fib(4) at its second call: line 6, one run
(0x1013395, 6, "call", [(0x1013370, C_)], None, ("text", "fib", VELLUM)),
(0x101339a, 6, "mov", [("qword ptr [rbp - 0x18], rax", P)], "trail2",
("chain", [(0x7fffffffed88, S_)], ("int", 2), None)),
(0x101339e, 6, "mov", [("rdi, qword ptr [rbp - 0x10]", P)], "trail1",
("chain", [(0x7fffffffed90, S_)], ("int", 4), None)),
(0x10133a2, 6, "sub", [("rdi, 2", P)], "trail0", ("set", "rdi", [], ("int", 2))),
(0x10133a6, 6, "call", [(0x1013370, C_)], "cur", ("text", "fib", BRIGHT)),
(0x10133ab, 6, "mov", [("rcx, rax", P)], None, ("set", "rdi", [], ("int", 2))), # the call's argument hangs here
(0x10133ae, 6, "mov", [("rax, qword ptr [rbp - 0x18]", P)], None, None),
(0x10133b2, 6, "add", [("rax, rcx", P)], None, None),
(0x10133b5, 6, "mov", [("qword ptr [rbp - 8], rax", P)], None, None),
]
FIB_BACKTRACE = [("fib+0", "n=2", "fib.c", 3), ("fib+59", "n=4", "fib.c", 6), ("fib+42", "n=5", "fib.c", 6),
("main+25", "", "fib.c", 10), ("libc_start_main_stage2+45", "", "__libc_start_main.c", 95),
("_start_c+0", "", "crt1.c", 15)]
def frame_calls(name):
"""fib(4) has called fib(2), mid-step: rsp and the return address struck, and the new node drawn from it."""
g = Svg()
sp = SUBJECT
y = TOP + sp["band"] + 12
ys = source(g, y, sp["src"], FIB_SRC, 3, 6, [7, 5, 4], "fib.c", len(FIB_SRC) - 1)
at = disasm(g, y + ph(sp["src"]) + 12, FIB_DIS, "fib", 6)
thread(g, ys, [(at[0x1013395], at[0x10133b5] + ROW)])
yr = TOP + sp["view"] + 12
registers(g, yr, FIB_REGS, FIB_FLAGS, {"rsp": {0: "strike"}, "rdi": {0: "tick"}})
rows = stack(g, yr + ph(17) + 12, FIB_STACK, FIB_FRAMES, rsp=0x7fffffffed78, roles={5: ("saved rbp", DIM)})
backtrace(g, TOP, sp["view"], FIB_BACKTRACE)
calls(g, TOP, sp["band"], fib_calls(5), 8, "main", project_from=rows[0])
clock(g, 752, 1999)
gen.caption(g, [[("The call pushed its return address, ",), ("fib+59", "mono"), (", on the stack.",)],
[("That word is the new frame, and the frame is the node ",), ("fib(2)", "mono"), (".",)]])
g.save(name)
# ---- the data: the sqlite scene (anim/scenes/sqlite.zig), its stops 120 and 169 ---------------------
SQ = "/home/goblin/05-genizah/sqlite/sqlite-amalgamation-3500400/sqlite3.c"
SQ_LINES = {n: l for n, l in enumerate(open(SQ, errors="replace").read().split("\n"), 1) if 42280 <= n <= 42300 or 80885 <= n <= 80905}
SQ_TOTAL = 262899
class Lines(dict):
"""The source's lines a mock shows, by number (sqlite3.c is 262 899 of them)."""
def __getitem__(self, i):
return SQ_LINES.get(i + 1, "")
def sq_region(v):
"""Where a value of the sqlite recording points, by its mappings: the ink of its digits."""
if 0x7ffffffde000 <= v < 0x7ffffffff000:
return S_
if 0x517000 <= v < 0x55b000:
return H_
if 0x510000 <= v < 0x517000:
return D_
if 0x402000 <= v < 0x4ed000 or 0x7ffff7c24000 <= v < 0x7ffff7d9f000:
return C_
return VELLUM
SQ_FLAGS_120 = [("CF", 0, 0), ("PF", 0, 1), ("AF", 0, 0), ("ZF", 0, 1), ("SF", 0, 0), ("IF", 1, 0), ("DF", 0, 0), ("OF", 0, 0)]
SQ_FLAGS_169 = [("CF", 1, 1), ("PF", 1, 1), ("AF", 0, 0), ("ZF", 0, 0), ("SF", 0, 0), ("IF", 1, 0), ("DF", 0, 0), ("OF", 0, 0)]
E980 = [(0x7fffffffe980, S_), (0x7fffffffeb90, S_), (0x7fffffffec60, S_), (0x7fffffffece0, S_), (0x7fffffffed00, S_)]
E7E0 = [(0x7fffffffe7e0, S_), (0x7fffffffe820, S_), (0x7fffffffe860, S_), (0x7fffffffe8d0, S_), (0x7fffffffe940, S_)]
SQ_REGS_120 = [
("rax", [(0x5226d0, H_)], ("int", 0)), ("rbx", [], ("int", 1)), ("rcx", [], ("int", 0)), ("rdx", [], ("int", 8)),
("rsi", [(0x7fffffffea60, S_)], ("int", 0)), ("rdi", [(0x521978, H_)], ("int", 0x101)),
("rbp", E980, None), ("rsp", E980, None), ("r8", [], ("int", 0x38)), ("r9", [], ("int", 0)),
("r10", [], ("int", 7)), ("r11", [], ("int", 0xffffffff)), ("r12", [], ("int", 0)),
("r13", [(0x5222d0, H_)], ("int", 0x39fb80)), ("r14", [(0x5218f8, H_)], ("int", 0x40100010000)),
("r15", [], ("int", 0)), ("rip", [(0x448d84, C_, "sqlite3BtreeInsert+4")], None),
]
PAGE_W = 0xe60f030000000d
SQ_REGS_169 = [
("rax", [], ("int", 0x1000)), ("rbx", [], ("int", 3)), ("rcx", [(0x7ffff7cf1a7d, C_, "__pwrite64+173")], None),
("rdx", [], ("int", 0x1000)), ("rsi", [(0x538b28, H_)], ("int", PAGE_W)), ("rdi", [], ("int", 3)),
("rbp", E7E0, None), ("rsp", [(0x7fffffffe7a0, S_)], ("int", 0)), ("r8", [], ("int", 0)), ("r9", [], ("int", 0)),
("r10", [], ("int", 0x1000)), ("r11", [], ("int", 0x246)), ("r12", [], ("int", 0x1000)),
("r13", [(0x538b28, H_)], ("int", PAGE_W)), ("r14", [], ("int", 0x1000)), ("r15", [(0x538b28, H_)], ("int", PAGE_W)),
("rip", [(0x422051, C_, "unixWrite+65")], None),
]
EA18 = [(0x7fffffffea18, S_), (0x517378, H_), (0x513010, D_)]
SQ_STACK_120 = [ # from rsp: sqlite3BtreeInsert's saved rbp and return address, then its caller's words
(0x7fffffffe980, ["rbp", "rsp"], E980[1:], None),
(0x7fffffffe988, [], [(0x43e029, C_, "sqlite3VdbeExec+18905")], None),
(0x7fffffffe990, [], [(0x7ffff7c0ed60, VELLUM)], ("int", 0xd001200000f05)),
(0x7fffffffe998, [], EA18, ("int", 0x7800000003)),
(0x7fffffffe9a0, [], [(0x521ed0, H_)], ("int", 0)),
(0x7fffffffe9a8, [], EA18, ("int", 0x7800000003)),
]
SQ_STACK_169 = [ # rsp+20 to rsp+48: the words unixWrite's prologue pushed, its saved rbp, its way back
(0x7fffffffe7c0, [], [], ("int", 0), {"end": "tick"}),
(0x7fffffffe7c8, [], [(0x538b28, H_)], ("int", PAGE_W), {1: "tick"}),
(0x7fffffffe7d0, [], [(0x517e38, H_), (0x513010, D_)], ("int", 0x7800000003), {1: "tick"}),
(0x7fffffffe7d8, [], [], ("int", 2), {"end": "tick"}),
(0x7fffffffe7e0, ["rbp"], E7E0[1:], None),
(0x7fffffffe7e8, [], [(0x42fa75, C_, "pager_write_pagelist+245")], None),
]
SQ_DIS_120 = [(a, 80895, mn, [(ops, P)], "cur" if a == 0x448d84 else None, None) for a, mn, ops in [
(0x448d80, "push", "rbp"), (0x448d81, "mov", "rbp, rsp"), (0x448d84, "push", "r15"), (0x448d86, "push", "r14"),
(0x448d88, "push", "r13"), (0x448d8a, "push", "r12"), (0x448d8c, "push", "rbx"), (0x448d8d, "sub", "rsp, 0xa8"),
(0x448d94, "mov", "r14d, ecx")]]
SQ_DIS_169 = [(a, 42290, mn, ops, "cur" if a == 0x422051 else "trail0" if a == 0x42204b else None,
("runs", [("", "arrow"), ("__pwrite64", VELLUM), (" = 4096", DIM)]) if a == 0x42204b else None)
for a, mn, ops in [
(0x422042, "mov", [("rsi, r15", P)]), (0x422045, "mov", [("rdx, r12", P)]), (0x422048, "mov", [("rcx, r14", P)]),
(0x42204b, "call", [("qword ptr [rip + 0xf1567]", P)]), (0x422051, "mov", [("r13, rax", P)]),
(0x422054, "test", [("r13d, r13d", P)]), (0x422057, "jns", [(0x422070, C_)]), (0x422059, "call", [(0x4021c0, C_)]),
(0x42205e, "mov", [("ecx, dword ptr [rax]", P)])]]
SQ_BT_120 = [("sqlite3BtreeInsert+4", "", "sqlite3.c", 80895), ("sqlite3VdbeExec+18905", "", None, 0),
("sqlite3_step+910", "", None, 0), ("sqlite3_exec+394", "", None, 0), ("main+56", "", None, 0),
("libc.so.6+27781", "", None, 0), ("__libc_start_main+137", "", None, 0), ("_start+37", "", None, 0)]
# BtreePayload (the source's lines 16740 to 16748), as the scene gives it: (at, len, reads, big, mark)
PAYLOAD = [(0, 8, "pointer", False, None), (8, 8, "number", False, 0), (16, 8, "pointer", False, None),
(24, 8, "pointer", False, None), (32, 2, "number", False, None), (36, 4, "number", False, 1),
(40, 4, "number", False, None)]
ROW_BYTES = bytes.fromhex("0000000000000000 0100000000000000 884d520000000000 0000000000000000"
"0000000007000000 0000000001000000".replace(" ", ""))
PAGE0 = bytes.fromhex("0d000000030fe6000ff70fef0fe60000")
PAGE_END = bytes.fromhex("0000000000000703021767616d6d61060202156265746107010217616c706861")
def leaf(page):
"""A table's leaf page, read by SQLite's file format (the scene's `leaf`): the header, the cell pointers,
each cell's length, rowid, record header and text. Every number big-endian, every varint here a byte."""
out = [(0, 1, "number", False, 0), (1, 2, "bytes", True, 0), (3, 2, "number", True, 0), (5, 2, "bytes", True, 0),
(7, 1, "bytes", False, 0)]
cells = page[3] << 8 | page[4]
out += [(8 + 2 * k, 2, "number", True, 1) for k in range(cells)]
for k in range(cells):
at = page[8 + 2 * k] << 8 | page[9 + 2 * k]
out += [(at, 1, "bytes", False, 2 + k), (at + 1, 1, "number", False, 2 + k), (at + 2, 2, "bytes", False, 2 + k),
(at + 4, page[at] - 2, "text", False, 2 + k)]
return out
def frame_sqlite(name, late):
"""The sqlite scene at rest. Early (stop 120): the backtrace is the band's drawing, and the row the B-tree
is handed, a struct on the stack, its view. Late (stop 169): pwrite64 has come back; the kernel's side is the
drawing, and the page it took the view, read by SQLite's file format."""
g = Svg()
sp = SUBJECT
y = TOP + sp["band"] + 12
yr = TOP + sp["view"] + 12
lines = Lines()
w = wide(SQ_TOTAL)
if not late:
source(g, y, sp["src"], lines, 80890, 80895, [], "sqlite3.c", SQ_TOTAL)
disasm(g, y + ph(sp["src"]) + 12, SQ_DIS_120, "sqlite3BtreeInsert", 80895, w=w)
ys = y + TAG + PAD + 5 * ROW
changed = {r: {0: "tick"} for r, _, _ in SQ_REGS_120 if r not in ("r12", "rip")}
registers(g, yr, SQ_REGS_120, SQ_FLAGS_120, changed)
stack(g, yr + ph(17) + 12, SQ_STACK_120, [("sqlite3BtreeInsert", 0, 1), ("sqlite3VdbeExec", 2, 9)],
rsp=0x7fffffffe980, roles={0: ("saved rbp", DIM)})
backtrace(g, TOP, sp["band"], SQ_BT_120, x=LX, note="newest at the bottom", focus=True)
base = 0x7fffffffea60
fields(g, TOP, sp["view"], "pX, the row: a BtreePayload, at rsi", base, 48, PAYLOAD,
{base + i: v for i, v in enumerate(ROW_BYTES)}, STACK, sq_region, marks=(0, 1))
clock(g, 9, 58)
gen.caption(g, [[("sqlite3VdbeExec", "mono"), (", the bytecode's loop, calls the B-tree: ",), ("rdi", "mono"), (" is",)],
[("the table's cursor, ",), ("rsi", "mono"), (" the row: rowid 1, a record of 7 bytes.",)]])
else:
source(g, y, sp["src"], lines, 42286, 42290, [], "sqlite3.c", SQ_TOTAL)
disasm(g, y + ph(sp["src"]) + 12, SQ_DIS_169, "unixWrite", 42290, w=w)
ys = y + TAG + PAD + 4 * ROW
changed = {r: {0: "tick"} for r, _, _ in SQ_REGS_169 if r not in ("r9", "rip")}
registers(g, yr, SQ_REGS_169, SQ_FLAGS_169, changed)
stack(g, yr + ph(17) + 12, SQ_STACK_169, [("unixWrite", -1, 5)], note="rsp+20 to rsp+48", rsp=0x7fffffffe7a0,
roles={4: ("saved rbp", DIM)})
page = bytes(4096 - len(PAGE_END) - len(PAGE0)) # the middle of the page is not drawn: `more`
page = PAGE0 + page + PAGE_END
F = FAINT
older = [("fsync", 0), ("openat", 5), ("fsync", 0), ("close", 0), ("pwrite64", 12), ("fsync", 0), ("pwrite64", 4096)]
log = [[(c, VELLUM), ("(…) = ", F), (str(r), VELLUM)] for c, r in older] # their arguments: not in this mock's data
log.append([("pwrite64", VELLUM), ("(fd ", F), ("3", VELLUM), (' "t.db"', F), (", buf ", F), ("538b28", HEAP),
(", count ", F), ("4096", VELLUM), (", offset ", F), ("4096", VELLUM), (") = ", F), ("4096", "held")])
calls_log(g, TOP, sp["band"], log)
base = 0x538b28
took = {base + i: v for i, v in enumerate(PAGE0)}
took.update({base + 0xfe0 + i: v for i, v in enumerate(PAGE_END)})
fields(g, TOP, sp["view"], "pBuf: page 2 of t.db, at rsi", base, 4096, leaf(page), took, HEAP, sq_region,
marks=(0, 1))
clock(g, 58, 58)
gen.caption(g, [[("Page 2 as the kernel took it: ",), ("0d", "mono"), (", a table's leaf; 3 cells;",)],
[("their offsets, ",), ("0ff7 0fef 0fe6", "mono"), (", each a row at the page's end.",)]])
thread(g, ys, [(y + ph(sp["src"]) + 12 + TAG + PAD, y + ph(sp["src"]) + 12 + TAG + PAD + 9 * ROW)])
g.save(name)
# ---- the call followed down: the syscalls scene's `open`, from main through the PLT and libc into the kernel ----
# `ztrace dbg` on anim/tools/hello.c (cc -O0 -no-pie -Wl,-z,now; env -i setarch -R): moments 1 (at the call),
# 2 (in the stub), 4 (at libc's `syscall`), 5 (after it) and 6 (back in main).
HELLO = open(__file__.replace("design/mock/context.py", "anim/tools/hello.c")).read().split("\n")
R_ = VELLUM # read-only data: the string, and the GOT once relro has sealed it
HM = [(0x401176, 4, "push", "rbp"), (0x401177, 4, "mov", "rbp, rsp"), (0x40117a, 4, "sub", "rsp, 0x40"), (0x40117e, 4, "mov", "rax, qword ptr fs:[0x28]"),
(0x401187, 4, "mov", "qword ptr [rbp - 8], rax"), (0x40118b, 4, "xor", "eax, eax"),
(0x40118d, 6, "lea", "rax, [rip + 0xe70]"), (0x401194, 6, "mov", "esi, 0"), (0x401199, 6, "mov", "rdi, rax"),
(0x40119c, 6, "mov", "eax, 0"), (0x4011a1, 6, "call", (0x401070, "open@plt")),
(0x4011a6, 6, "mov", "dword ptr [rbp - 0x38], eax"), (0x4011a9, 7, "lea", "rcx, [rbp - 0x30]"),
(0x4011ad, 7, "mov", "eax, dword ptr [rbp - 0x38]"), (0x4011b0, 7, "mov", "edx, 0x20"),
(0x4011b5, 7, "mov", "rsi, rcx"), (0x4011b8, 7, "mov", "edi, eax"), (0x4011ba, 7, "call", (0x401060, "read@plt")),
(0x4011bf, 7, "mov", "dword ptr [rbp - 0x34], eax")]
OPEN_ARGS = [("set", "rdi", [(0x402004, R_)], ("str", "note")), ("runs", [("rsi ", DIM), ("O_RDONLY", VELLUM)])]
STATIC = {0x40117e: ("runs", [("the stack's canary", DIM)]), # what a row says before it runs, and after
0x40118d: ("runs", [("= ", FAINT), (0x402004, R_), (' "note"', LIT)]),
0x4011ba: ("text", "read", VELLUM)}
def main_rows(first, n, states, notes):
out = []
for a, line, mn, ops in HM:
if a < first or len(out) == n:
continue
parts = [(ops, CODE)] if isinstance(ops, tuple) else [(ops, P)]
out.append((a, line, mn, parts, states.get(a), notes.get(a, STATIC.get(a))))
return out
LIBC_OPEN = [(0x7ffff7d10fb6, "xor", "r8d, r8d"), (0x7ffff7d10fb9, "mov", "rdi, 0xffffffffffffff9c"),
(0x7ffff7d10fc0, "mov", "eax, 0x101"), (0x7ffff7d10fc5, "syscall", ""), (0x7ffff7d10fc7, "mov", "rdx, rax"),
(0x7ffff7d10fca, "cmp", "rax, -0x1000"), (0x7ffff7d10fd0, "ja", 0x7ffff7d10fe8),
(0x7ffff7d10fd2, "mov", "eax, edx")]
def frame_descent(name):
"""Mock 16: four instants of one call followed down, each the program column of the working frame (`beside`):
the source over the disassembly, as a descent of windows by call depth."""
gen.W, gen.H = 3840, 1000
g = Svg()
syscall_args = [("set", "rdi", [], ("int", -100)), ("set", "rsi", [(0x402004, R_)], ("str", "note")),
("runs", [("rdx ", DIM), ("O_RDONLY", VELLUM)]), ("runs", [("r10 ", DIM), ("0", VELLUM)])]
call_c = ("runs", [("open", BRIGHT), ('("note", O_RDONLY)', VELLUM)])
instants = [
("1", "at the call", "moment 1", None, "main",
[("main", None, main_rows(0x40117a, 17, {0x401194: "trail2", 0x401199: "trail1", 0x40119c: "trail0", 0x4011a1: "cur"},
{0x401194: ("set", "rsi", [], ("int", 0)),
0x401199: ("set", "rdi", [(0x402004, R_)], ("str", "note")),
0x40119c: ("set", "rax", [], ("int", 0)),
0x4011a1: ("runs", [("open", BRIGHT), (" in libc, by the PLT", FAINT)]),
0x4011a6: OPEN_ARGS[0], 0x4011a9: OPEN_ARGS[1]}))],
["main calls open by its stub in the PLT. The arguments",
'are in rdi and rsi: "note" and O_RDONLY.']),
("2", "in the stub", "moment 2", "main waits at line 6 · the pc is in the PLT", "open@plt · the PLT",
# main keeps one row after its call and gives the rest above it: the stub's head is under its return row
[("main", None, main_rows(0x401176, 12, {0x401199: "trail2", 0x40119c: "trail1", 0x4011a1: "wait"},
{0x4011a1: call_c})),
("open@plt", "the PLT · its jmp reads open@got, 403fd8",
[(0x401070, None, "jmp", [("qword ptr [rip + 0x2f62]", P)], "cur",
("runs", [("", "arrow"), (0x7ffff7d10ec0, CODE), (" open", VELLUM)])),
(0x401076, None, "push", [("4", P)], None, ("text", "lazy binding: unused", FAINT)),
(0x40107b, None, "jmp", [(0x401020, CODE)], None, None),
(0x401080, None, "endbr64", [], "other_first", ("text", "_start", DIM))])],
["The call pushed main+48 and went down: main's window keeps",
"its call, ringed; the stub's opens under it, and its jmp reads the GOT."]),
("3", "the crossing", "moments 4 and 5", "main waits at line 6 · the pc is in libc's open",
"open · libc.so.6",
[("main", None, main_rows(0x40119c, 3, {0x40119c: "trail2", 0x4011a1: "wait"}, {0x4011a1: call_c})),
("open@plt", "the PLT, jumped through", [(0x401070, None, "jmp", [("qword ptr [rip + 0x2f62]", P)], "pass",
("runs", [("", "arrow"), (0x7ffff7d10ec0, CODE), (" open", VELLUM)]))]),
("open", "libc.so.6 · no source",
[(a, None, mn, [(ops, CODE)] if isinstance(ops, int) else ([(ops, P)] if ops else []),
{0x7ffff7d10fb6: "trail2", 0x7ffff7d10fb9: "trail1", 0x7ffff7d10fc0: "trail0", 0x7ffff7d10fc5: "cur"}.get(a),
{0x7ffff7d10fb6: ("set", "r8", [], ("int", 0)),
0x7ffff7d10fb9: ("runs", [("rdi ", DIM), ("-100", VELLUM), (" AT_FDCWD", FAINT)]),
0x7ffff7d10fc0: ("runs", [("rax ", DIM), ("0x101", VELLUM), (" 257", FAINT)]),
0x7ffff7d10fc5: ("runs", [("openat", BRIGHT), (" nr 257", FAINT)]),
0x7ffff7d10fc7: syscall_args[0], 0x7ffff7d10fca: syscall_args[1],
0x7ffff7d10fd0: syscall_args[2], 0x7ffff7d10fd2: syscall_args[3]}.get(a))
for a, mn, ops in LIBC_OPEN]),
("kernel", "openat, system call 257",
[[("openat(AT_FDCWD, \"note\", O_RDONLY, 0)", PAGE)],
[("returns ", gen.KERNEL_DIM), ("3", "struck"), (' "note"', PAGE), (" rcx, r11: clobbered", gen.KERNEL_DIM)]])],
["libc's open is a wrapper: it puts openat's number in rax",
"and its arguments in rdi, rsi, rdx, r10; syscall crosses down."]),
("4", "back up", "moment 6", None, "main",
[("main", None, main_rows(0x40117a, 17, {0x401199: "trail2", 0x40119c: "trail1", 0x4011a1: "trail0", 0x4011a6: "cur"},
{0x4011a1: ("runs", [("open", VELLUM), ('("note", O_RDONLY) = ', DIM), ("3", VELLUM)]),
0x4011a6: ("chain", [(0x7fffffffecc8, S_)], ("int", 0), None)}))],
["open's ret came straight back to main+48: the stub was a jump,",
"not a call. The windows close up, and eax holds 3, the descriptor."]),
]
for k, (num, title, when, waiting, note, windows, cap) in enumerate(instants):
dx = k * 928
g.o.append(f'')
g.t(LX, 40, num, 28, GOLD, "sansb")
g.t(LX + 28, 40, title, 28, VELLUM, "sansm")
g.t(LX + CW, 40, when, 20, FAINT, "sans", "end")
ys = source(g, 64, 8, HELLO, 3, 6, [] if waiting else [], "hello.c", 11, waiting=waiting)
at = descent(g, 300, windows, note=note)
run = [a for a in (0x40118d, 0x401194, 0x401199, 0x40119c, 0x4011a1, 0x4011a6) if a in at]
thread(g, ys, [(at[run[0]], at[run[-1]] + ROW)], *((VELLUM, 2) if waiting else (GOLD, 3)))
for i, line in enumerate(cap):
g.t(LX, 800 + i * 40, line, 28, VELLUM, "sans")
g.o.append("")
g.save(name)
def frame_operands(name):
"""Mock 17: real rows, as the disassembler writes them and as canim draws them: no size words, and a
`width` where no register of the instruction says the size; then the row's detail on rows of the strip."""
gen.W, gen.H = 1920, 640
g = Svg()
L = 0x7ffff7c00000 # libc's base in the recording
rows = [(0x100191b, "nop", "dword ptr [rax + rax]", "list"), (0x1001926, "mov", "rdi, qword ptr [rdi + 8]", "list"),
(0x100192a, "mov", "qword ptr [rax + 8], rcx", "list"), (0x40117e, "mov", "rax, qword ptr fs:[0x28]", "hello"),
(0x4011a6, "mov", "dword ptr [rbp - 0x38], eax", "hello"),
(0x401070, "jmp", "qword ptr [rip + 0x2f62]", "hello"),
(L + 0x110f07, "mov", "eax, dword ptr [r11 + 0x308]", "libc"),
(L + 0x110f0e, "cmp", "byte ptr [rip + 0x11018b], 0", "libc"),
(L + 0x110f94, "mov", "dword ptr [rbp - 0x60], 0x10", "libc"),
(L + 0x110f9b, "movsxd", "r10, dword ptr [rbp - 0x30]", "libc"),
(L + 0x110f85, "mov", "dword ptr fs:[rax], edx", "libc"),
(L + 0x110fe5, "nop", "dword ptr [rax]", "libc")]
for k, (title, sizes) in enumerate([("as the disassembler writes them", True), ("as canim draws them", False)]):
x0 = 64 + k * 912
g.o.append(f'')
y0 = panel(g, LX, 48, CW, len(rows), title, focus=not sizes, note="list, hello, libc's open")
for i, (a, mn, ops, where) in enumerate(rows):
yy = y0 + i * ROW
addr(g, LX + DX_ADDR, yy, a, CODE) # libc's twelve digits move the columns after them by 60
g.t(LX + DX_MN + 60, b(yy), mn, S, FAINT if mn == "nop" else KW, MONO if mn == "nop" else BOLD)
operands(g, LX + DX_OPS + 60, yy, mn, ops, VELLUM, sizes)
g.o.append("")
detail = [
(0x40117e, "mov", "rax, qword ptr fs:[0x28]", ("runs", [("the stack's canary ", DIM), ("191a6a1f012bed00", VELLUM)])),
(0x40118d, "lea", "rax, [rip + 0xe70]", ("runs", [("rip + 0xe70 = ", FAINT), (0x402004, R_), (' "note"', LIT)])),
(0x401070, "jmp", "qword ptr [rip + 0x2f62]",
("runs", [("", "arrow"), (0x7ffff7d10ec0, CODE), (" open", VELLUM), (" · read from open@got, ", FAINT),
(0x403fd8, R_)])),
(L + 0x110f0e, "cmp", "byte ptr [rip + 0x11018b], 0",
("runs", [("1", VELLUM), (" : ", FAINT), ("0", VELLUM), (" ", FAINT), ("zf", DIM), (" ", FAINT)])),
(L + 0x110f15, "jne", L + 0x110fb0, ("runs", [("taken", VELLUM), (" · reads ", FAINT), ("zf", DIM),
(" → 7ffff7d10fb0 open+240", DIM)])),
(L + 0x110fca, "cmp", "rax, -0x1000", ("runs", [("3", VELLUM), (" : ", FAINT), ("-4096", VELLUM), (" ", FAINT),
("CF", "chip"), ("zf", DIM)])),
(L + 0x110fd0, "ja", L + 0x110fe8, ("runs", [("not taken", DIM), (" · reads ", FAINT), ("CF", "chip"),
("zf", DIM)])),
]
y0 = panel(g, LX, 48 + ph(len(rows)) + 36, CW * 2 + 32, len(detail), "the row's detail",
note="what a row says: a name for a known place, lea's sum, the slot a jump goes through, a compare's two values and the flags it leaves")
insn_rows(g, y0, [(a, None, mn, [(ops, CODE)] if isinstance(ops, int) else [(ops, P)], None, note)
for a, mn, ops, note in detail], None, lead=0)
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(9) == BOTTOM - TOP - 296 - 12 # lens as subject: the drawing
assert ph(17) + 12 + ph(6) == BOTTOM - TOP - 200 - 12 and ph(7) == 200 # its view, and the stack under it
assert ph(5) == 152
assert shared([0x1001910, 0x1001937]) == 5 and shared([0x28b41070]) == 6
# 9 to 11 are map.py's: the working frame from the fresh recording, with its minimap
frame_calls("12-calls-subject")
frame_sqlite("13-sqlite-row", False)
frame_sqlite("14-sqlite-page", True)
frame_descent("16-descent")
frame_operands("17-operands")