From c3d9f7ba5effd615374b1359ad98ecf801559f83 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 11 Nov 2026 00:06:30 -0300 Subject: canim: a call followed down to the kernel; rows that say what they do; the heap from the inside From the user. The disassembly can descend: the syscalls scene is glibc's hello by instruction, and open is followed from main through its PLT stub, whose jmp reads the GOT, into libc's wrapper to the syscall row, which crosses to the kernel's window under it, and back up. The band keeps the calls so far as strace writes them. Operands lose their size words and show a width as byte cells only where nothing else says it. A compare shows its values and the flags it leaves, a jump the flags it reads, lea its result, an indirect jump its target and the slot it read, a call that has run its C form. The backtrace has its newest frame at the bottom. A new scene shows glibc 2.44's heap from blocks that exist: chunks read by fields (a size with its bits, a protected pointer), the free list as arcs, the tcache in a loupe, the program's list over malloc's own. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- anim/scenes/syscalls.zig | 96 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 66 insertions(+), 30 deletions(-) (limited to 'anim/scenes/syscalls.zig') diff --git a/anim/scenes/syscalls.zig b/anim/scenes/syscalls.zig index 1c875f3..db67045 100644 --- a/anim/scenes/syscalls.zig +++ b/anim/scenes/syscalls.zig @@ -1,12 +1,17 @@ //! A program that needs the kernel four times: open, read, close, write. -//! The debugger's context, and the kernel's side of each call as the lens. +//! glibc's `hello`, by instruction from main: `open` followed down (the +//! disassembly a `descent`: main's call, the PLT's stub, libc's wrapper, +//! the kernel's window at the floor, and back up), then the other three +//! stepped over, each crossing under its call. The band is the calls so +//! far, as strace writes them. //! -//! How it moves (design/motion.md): no effect before its cause. Each call -//! has its own caption, up a second before the line fires; the registers -//! that carry it are framed one at a time; the arrow goes down through -//! the line, and only then does the kernel's side take the call: its -//! name, its rows, its card. The bytes are copied two frames apart; the -//! arrow comes back; `rax` is struck. A call is as long as what it does. +//! How it moves (design/motion.md, "A call followed down", "A system +//! call"): no effect before its cause. Each beat has its caption first; +//! the call row's plaque becomes a ring and the lane draws down to the +//! callee's head before its rows come; the registers that carry the call +//! are framed one at a time; the crossing lane goes down before the +//! kernel's window opens; `returns` has the value before rax is struck. +const std = @import("std"); const anim = @import("anim"); const canim = @import("canim"); const recordings = @import("recordings"); @@ -14,39 +19,70 @@ const recordings = @import("recordings"); pub const background = canim.background; pub const scene = anim.Live(frame, struct {}); -/// What the narrator says before each of main's calls, in order. -const lines = [_][]const u8{ - "`open`: a name goes down, and a small number comes back.\nThat number is the file from now on.", - "`read`: the kernel copies the file's bytes into `buf`,\nand says how many.", - "`close`: the number is handed back.", - "`write`: the same bytes go the other way,\nfrom `buf` to file number 1, the output.", -}; +/// The first moment from `from` whose pc is named `name` (`open@plt+0`). +fn at(rec: *canim.Recording, from: u64, name: []const u8) u64 { + var i = from; + while (i < rec.end()) : (i += 1) if (std.mem.eql(u8, rec.strings.get(rec.register(i, "rip")) orelse "", name)) return i; + return rec.end(); +} + +/// The first moment from `from` whose instruction is `text`. +fn on(rec: *canim.Recording, from: u64, text: []const u8) u64 { + var buf: [256]u8 = undefined; + var i = from; + while (i < rec.end()) : (i += 1) if (rec.instruction(i, rec.register(i, "rip"), &buf)) |here| if (std.mem.startsWith(u8, here.text, text)) return i; + return rec.end(); +} fn frame(s: *anim.Frame) void { const rec = canim.open(recordings.hello); - // From main's first line to its last: its first lines walked under the - // first caption, then a call a phrase. - var at = canim.cursor(s, rec, rec.call("main", 0).enter); - at.journey(.line, rec.lineMoment(10, at.first)); - const split = canim.layout.split.subject; - at.levels = .{ .source_rows = 10 }; - const ctx = canim.context(s, at, .{ .split = split, .syscalls = true }); - // The lens: the kernel's side of each call. - const kernel = canim.crossing(s, .{ .cursor = at, .stage = ctx.stage, .focus = true }); - ctx.map.add(s, canim.Crossing{ .cursor = at, .stage = ctx.map.stage }); + const main = rec.call("main", 0); + var cur = canim.cursor(s, rec, main.enter); + const stub = at(rec, main.enter, "open@plt+0"); + const crossing = on(rec, stub, "syscall"); + const back = on(rec, crossing, "ret"); + const done = rec.lineMoment(10, back); + cur.journey(.moment, done); + cur.levels = .{ .source_rows = 8, .fire = .disasm }; + const ctx = canim.context(s, cur, .{ .split = canim.layout.split.beside, .syscalls = true, .descent = true }); + const log = canim.crossing(s, .{ .cursor = cur, .stage = ctx.stage, .focus = true }); + ctx.map.add(s, canim.Crossing{ .cursor = cur, .stage = ctx.map.stage }); var says: canim.Narrator = .{}; const t = canim.theme.time; - const joins = ctx.ties(s); - canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, kernel, joins }); - says.line(s, "A program cannot open a file or reach the screen itself.\nIt asks the kernel, and waits."); - at.walk(s, .line, rec.lineMoment(6, at.first)); + canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, log, joins }); + + says.line(s, "A program cannot open a file itself.\nIt asks the kernel, and waits."); + cur.walk(s, .line, rec.lineMoment(6, main.enter)); + cur.walk(s, .moment, stub - 1); + says.line(s, "`main` calls `open` by its stub in the PLT. The arguments\nare in rdi and rsi: \"note\" and O_RDONLY."); + canim.descent.step(cur, s, .moment); + s.wait(t.phrase_rest); + says.line(s, "The call went down: main's window keeps its call, ringed;\nthe stub's jmp reads the GOT, and goes on to libc."); + canim.descent.step(cur, s, .moment); + s.wait(t.phrase_rest); + says.line(s, "libc's `open` is a wrapper: it puts openat's number in rax\nand its arguments in rdi, rsi, rdx and r10."); + cur.hurry(s, .moment, crossing, .{}); + says.line(s, "`syscall` crosses down. The kernel opens the file\nand answers in rax: 3, the descriptor."); + canim.descent.step(cur, s, .moment); + s.wait(t.phrase_rest); + cur.hurry(s, .moment, back, .{}); + says.line(s, "`open`'s ret comes straight back to main: the stub\nwas a jump, not a call. The windows close up."); + canim.descent.step(cur, s, .moment); + s.wait(t.phrase_rest); - // One call a phrase: its caption while nothing moves, then the crossing. + // The other three, stepped over: each crossing opens under its call. + const lines = [_][]const u8{ + "`read`: the kernel copies the file's bytes into `buf`,\nand says how many.", + "`close`: the number is handed back.", + "`write`: the same bytes go the other way,\nfrom `buf` to file number 1, the output.", + }; + cur.walk(s, .line, rec.lineMoment(7, back)); for (lines) |line| { says.line(s, line); - canim.syscalls.step(at, s, .line); + canim.syscalls.step(cur, s, .line); s.wait(t.phrase_rest); } + cur.walk(s, .line, done); says.close(s); } -- cgit v1.3