russell@unturf.com
aff292ebc8
Fox flagged that the "A diagram is worth 10,000 words" quote
appeared twice in the paper but nothing was actually illustrated.
Fixed by:
1. Refreshing every .dot source to match current reality:
- docs/asm-architecture.dot: 22 KB (was "13 KB"), 14 syscalls
(was 4), 91 builtins (was 34), djb2 hash (was "linear scan"),
TCP stack + heap-snapshot + portal boxes added.
- docs/benchmark-sumto.dot: sum-to(1M) i5-8350U numbers; C
--fast 238 ms, asm 670 ms, Python --fast 5,136 ms. Was
sum-to(50k) with stale numbers.
- docs/benchmark-ack.dot: ackermann(3,8) i5-8350U numbers. Was
ack(3,4) with stale numbers.
- docs/benchmark-binary-size.dot: asm 22 KB, C 205 KB, busybox
2.1 MB, python3 8.0 MB. Was comparing against different
baselines.
2. Regenerated all PNGs via `make docs`.
3. Embedded in the paper at meaningful points:
- §2 Architecture (Python): python-architecture.png
- §6.4 Three-way bench: benchmark-sumto.png, benchmark-ack.png
- §11 Three Implementations: c-architecture.png, asm-
architecture.png
- §11.3 HTTP + sockets: benchmark-binary-size.png
4. Removed the redundant quote from §12.3; the one in §11
remains because §11 now follows it with two real diagrams.
Prerequisite fox noted: "make sure diagrams are up to date before
using them to code." Done — every embedded figure has the current
numbers/topology, not the old ones.
73 lines
3.2 KiB
Text
73 lines
3.2 KiB
Text
// Assembly implementation architecture — 2026-04-17 refresh
|
|
// "A diagram is worth 10,000 words." — russell@unturf.com
|
|
digraph asm_arch {
|
|
rankdir=TB
|
|
node [shape=box, style=filled, fontname="Helvetica"]
|
|
edge [fontname="Helvetica", fontsize=10]
|
|
|
|
subgraph cluster_binary {
|
|
label="Binary: 22 KB stripped, zero dependencies"
|
|
style=rounded
|
|
color="#333333"
|
|
fontcolor="#333333"
|
|
start [label="_start\nno libc\nno main()" fillcolor="#2d3436" fontcolor=white]
|
|
}
|
|
|
|
subgraph cluster_syscalls {
|
|
label="14 Linux Syscalls — no libc"
|
|
style=rounded
|
|
color="#666666"
|
|
fs_io [label="File I/O\nread(0) write(1)\nopen(2) close(3)\nlseek(8)" fillcolor="#dfe6e9"]
|
|
mem_io [label="Memory\nmmap(9) munmap(11)" fillcolor="#dfe6e9"]
|
|
net_io [label="Sockets\nsocket(41) connect(42)\naccept(43) bind(49)\nlisten(50) setsockopt(54)" fillcolor="#dfe6e9"]
|
|
misc [label="Misc\nclock_gettime(228)\nexit(60)" fillcolor="#dfe6e9"]
|
|
}
|
|
|
|
subgraph cluster_memory {
|
|
label="Memory Model"
|
|
style=rounded
|
|
color="#666666"
|
|
bump [label="Bump Allocator\n%r15 = heap ptr\n%r13 = heap limit\nheap_grow mmaps 64 MB" fillcolor="#ffeaa7"]
|
|
snap [label="heap-snapshot\nheap-restore\narena for per-request\nloops (O(1) memory)" fillcolor="#ffeaa7"]
|
|
tags [label="Tag-in-Low-3-Bits\n0=int 1=pair 2=sym\n3=closure 4=builtin\n5=special 6=string\n7=vector" fillcolor="#ffeaa7"]
|
|
}
|
|
|
|
subgraph cluster_interp {
|
|
label="Interpreter — 4,968 lines of GNU asm (GAS AT&T syntax)"
|
|
style=rounded
|
|
color="#666666"
|
|
tokenize [label="Tokenizer\nchar-by-char\n\\n \\r \\t \\0 escapes" fillcolor="#fff3cd"]
|
|
read_fn [label="Reader\nrecursive descent\n→ tagged cons cells\n(load), read-from-string" fillcolor="#fff3cd"]
|
|
eval_fn [label="Evaluator\nTCO via jmp .eval_top\nall special forms\n+ eval as builtin" fillcolor="#d4edda"]
|
|
print_fn [label="Printer\nitoa, list, vector\ncustom output_fd\nport-aware" fillcolor="#81ecec"]
|
|
builtins [label="91 Builtins (was 34)\narith cons car cdr list ...\nload ports write-file\nportal-save/resume\ntcp-listen/accept/send/recv\nread-from-string eval" fillcolor="#a29bfe"]
|
|
}
|
|
|
|
subgraph cluster_env {
|
|
label="Environment"
|
|
style=rounded
|
|
color="#666666"
|
|
env_chain [label="Linked List\n24 bytes per binding\n[sym | val | next]\n← allocation hot path" fillcolor="#e2d5f1"]
|
|
sym_intern [label="Symbol Table\ndjb2 hash, 1024 buckets\nO(1) intern\n(MOAD-0001 fixed)" fillcolor="#e2d5f1"]
|
|
}
|
|
|
|
start -> mem_io [label="allocate heap"]
|
|
start -> fs_io [label="read input"]
|
|
fs_io -> tokenize
|
|
tokenize -> read_fn
|
|
read_fn -> eval_fn
|
|
eval_fn -> eval_fn [label="TCO: jmp" style=bold color=red]
|
|
eval_fn -> builtins [label="apply"]
|
|
eval_fn -> env_chain [label="lookup/define"]
|
|
eval_fn -> print_fn [label="result"]
|
|
print_fn -> fs_io
|
|
builtins -> net_io [label="tcp-*"]
|
|
builtins -> fs_io [label="(load), file I/O"]
|
|
env_chain -> sym_intern
|
|
bump -> tags
|
|
bump -> snap [label="arena pattern" style=dashed]
|
|
eval_fn -> bump [label="cons/closure alloc"]
|
|
|
|
{rank=same; fs_io; mem_io; net_io; misc}
|
|
{rank=same; tokenize; read_fn}
|
|
}
|