From dc3b58781420be6070fca896e55776bc27db905d Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 20:16:54 -0300 Subject: canim: a scene from a real program: SQLite's row on its way to disk Three inserts stopped at sqlite3BtreeInsert with their payloads read off the caller's stack, the commit's backtrace from unixWrite up to main, the pwrite64 crossing into the kernel, and page 2 as the kernel took it: its header, its cell pointers and the three rows, read by field. The scene is built only where SQLite's source is (-Dsqlite=DIR); its recording is 181 moments, 95 KB. What a real program asked of the blocks: a dump read by the fields a scene gives it, with the rows between collapsed; addresses of twelve digits and line numbers of six; the backtrace as a lens's drawing; a continue's motion (shared frames slide, a far window fades); memory drawn only where the stop read it. In the kernel lens a register is framed as carrying an argument only while it holds it at the stop shown, and an allocator row is read only where an allocation follows the word. Co-Authored-By: Claude Fable 5.2 --- anim/src/syscalls.zig | 98 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 34 deletions(-) (limited to 'anim/src/syscalls.zig') diff --git a/anim/src/syscalls.zig b/anim/src/syscalls.zig index 67085c2..b3e080d 100644 --- a/anim/src/syscalls.zig +++ b/anim/src/syscalls.zig @@ -29,8 +29,8 @@ const k = theme.color.on_kernel; /// kernel's side change, the last call giving way to this one, its name, /// its rows, its card; the work is done a byte at a time (a call with /// none skips it); the arrow comes back, and what came back strikes rax. -/// So a call is as long as what it does: `close` 4.0 s, a `read` of -/// fifteen bytes 5.1. +/// So a call is as long as what it does: `close` 4.1 s, a `read` of +/// fifteen bytes 5.2. pub const Plan = struct { registers: f32 = time.cascade, enters: f32 = 0.80, @@ -45,14 +45,16 @@ pub const Plan = struct { work: f32 = 2.00, fills: f32 = 2.40, bytes: f32 = 0, - /// The arrow back sets off; rax is struck; the `returns` row takes the - /// value; the program stores what came back (memory, after its - /// cause); the mark moves on. + /// The arrow back sets off; as it lands the `returns` row takes the + /// value; then rax is armed, and struck (nothing is marked as come + /// back before it has); the program stores what came back (memory, + /// after its cause); the mark moves on. back: f32 = 2.00, returns: f32 = 2.40, - stored: f32 = 2.80, - advance: f32 = 3.40, - total: f32 = 4.00, + struck: f32 = 2.60, + stored: f32 = 2.90, + advance: f32 = 3.50, + total: f32 = 4.10, pub const cross = 0.40; pub const row = 0.10; @@ -66,7 +68,8 @@ pub const Plan = struct { p.bytes = @floatFromInt(@max(down, @min(up, 32))); if (p.bytes > 0) p.back = p.fills + p.bytes * byte + 10.0 / 60.0; p.returns = p.back + cross; - p.stored = p.returns + row + time.cascade; + p.struck = p.returns + time.strike.arm; + p.stored = p.struck + time.cascade; p.advance = p.stored + time.read_value; p.total = p.advance + time.step + time.rest; return p; @@ -97,6 +100,16 @@ pub fn step(c: cursors.Cursor, s: *anim.Frame, by: Recording.Stop) void { c.step(s, to, p.step(), p.total); } +/// How long after its slot in the cascade a register this step changed +/// strikes, in a step drawn as a crossing: once the call is back, after +/// rax. 0 in any other step. +pub fn crossingDelay(now: cursors.Now) f32 { + if (!now.crossings) return 0; + const made = inStep(now) orelse return 0; + const p = Plan.of(made); + return p.struck - p.registers; +} + /// The argument registers of a syscall, in order. const carriers = [_][]const u8{ "rdi", "rsi", "rdx", "r10", "r8", "r9" }; @@ -110,10 +123,13 @@ pub fn latest(rec: *const Recording, i: u64) ?usize { return found; } -/// The syscall the cursor's step made (the newest, when it made several). +/// The syscall the cursor's step made, crossed on screen. A step that made +/// several (a debugger's continue through a library's calls) crosses none: +/// it is a step like any other, and the kernel's side shows the newest. pub fn inStep(now: cursors.Now) ?Recording.Syscall { const n = latest(now.rec, now.stops[0]) orelse return null; const call = now.rec.syscalls[n]; + if (n > 0 and now.rec.syscalls[n - 1].enter > now.stops[1]) return null; return if (call.enter > now.stops[1]) call else null; } @@ -147,12 +163,15 @@ pub const Crossing = struct { cursor: cursors.Cursor, stage: *const Stage, focus: bool = false, + /// Its view, the bytes of the newest call: false where the scene's own + /// view stands over the state column (`hexdump.Dump`). + view: bool = true, const row_h = theme.metric.context.row; const size = theme.size.mono.context; pub fn draw(c: *const Crossing, f: *sk.Frame, placed: anim.Placed) void { - c.view(f, placed); + if (c.view) c.bytesView(f, placed); const box = c.stage.box(placed, .band); if (box.h < theme.metric.context.tag + 24) return; const u = context.at(f, placed, box).faded(placed.value(c.stage.drawing)); @@ -167,7 +186,7 @@ pub const Crossing = struct { defer u.unclip(); u.text(.sans, theme.size.sans.micro, 12, body.y + 22, "calls so far", k.dim); const newest = latest(rec, now.stops[0]) orelse return; - const live = rec.syscalls[newest].enter > now.stops[1] and now.walking(); + const live = inStep(now) != null and now.walking(); const p = Plan.of(rec.syscalls[newest]); const t: f32 = if (live) now.time else std.math.inf(f32); if (t >= p.enters) arrows(u, body, t, p, rec.syscalls[newest]); @@ -196,7 +215,7 @@ pub const Crossing = struct { v.frame(card, k.ink, theme.stroke.rule); const name = zt.syscalls.name(done.nr) orelse "?"; // The result ranged right, when it is short; the name has the rest, and is cut only there. - const words = if ((i != newest or t >= p.returns + Plan.row) and done.exit != null) result(u, done) else ""; + const words = if ((i != newest or t >= p.returns) and done.exit != null) result(u, done) else ""; const said = if (words.len > 0 and words.len <= 4) words else ""; if (said.len > 0) v.text(.mono, size, card.x + card.w - 8 - u.width(.mono, size, said), theme.baseline(card.y, card.h, size), said, k.dim); v.text(if (gold) .mono_bold else .mono, size, card.x + 8, theme.baseline(card.y, card.h, size), rows.fitted(u, name, card.w - 16 - (if (said.len > 0) u.width(.mono, size, said) + 12 else 0)), k.ink); @@ -206,12 +225,12 @@ pub const Crossing = struct { /// Its view: the bytes the newest call is given or fills (its path, a /// buffer), as a dump over the state column; struck as the kernel /// fills them. - fn view(c: *const Crossing, f: *sk.Frame, placed: anim.Placed) void { + fn bytesView(c: *const Crossing, f: *sk.Frame, placed: anim.Placed) void { const rec = c.cursor.rec; const now = c.cursor.now(placed); var newest = latest(rec, now.stops[0]); // No effect before its cause: until the kernel has taken the call, the last one's bytes. - if (newest) |n| if (rec.syscalls[n].enter > now.stops[1] and now.walking() and now.time < Plan.of(rec.syscalls[n]).name) { + if (newest) |n| if (inStep(now) != null and now.walking() and now.time < Plan.of(rec.syscalls[n]).name) { newest = if (n > 0) n - 1 else null; }; const made: ?Recording.Syscall = if (newest) |n| rec.syscalls[n] else null; @@ -222,9 +241,20 @@ pub const Crossing = struct { defer v.u.unclip(); const sp = span orelse return; if (v.rows == 0) return; - const first = sp.addr & ~@as(u64, 15); - const n = @min(v.rows, (sp.addr + sp.len - first + 15) / 16); - hexdump.draw(v.u, now, 0, theme.metric.context.tag + theme.metric.context.pad, first, n, .{ .region = context.ink(context.regionOf(now.moment(), sp.addr)) }); + // The bytes it names are the field the view is about: a path or a + // buffer of text reads as text, anything else is left to the eye. + const given = made.?; + const text = given.text[0..@min(given.text.len, sp.len)]; + const printable = for (text) |byte| { + if (!std.ascii.isPrint(byte) and byte != '\n' and byte != '\t' and byte != 0) break false; + } else true; + hexdump.fielded(v, now, theme.metric.context.tag + theme.metric.context.pad, .{ + .base = sp.addr, + .len = sp.len, + .fields = &.{.{ .at = 0, .len = sp.len, .reads = if (printable) .text else .bytes }}, + .region = context.ink(context.regionOf(now.moment(), sp.addr)), + .given = .{ .addr = sp.addr, .bytes = text, .shows = 1 }, + }); v.veil(now); } @@ -263,7 +293,7 @@ pub const Crossing = struct { row(u.faded(shows), row_y, carriers[arg], meaning, value(u, made, kind, arg, &text_used), note); row_y += row_h + 4; } - const back = t >= p.returns + Plan.row and made.exit != null; + const back = t >= p.returns and made.exit != null; // What `open` returns is a descriptor: open on the path it was given. const opened = back and std.mem.eql(u8, zt.syscalls.name(made.nr) orelse "", "open") and @as(i64, @bitCast(made.result)) >= 0; row(u.faded(std.math.clamp((t - p.rows - @as(f32, @floatFromInt(@min(signature.len, 4))) * Plan.row) / Plan.row, 0, 1)), row_y, "rax", "returns", if (back) result(u, made) else "\u{2014}", if (opened) rec.openOn(u.f.scratch, made.result, made.exit.? + 1) else ""); @@ -273,6 +303,9 @@ pub const Crossing = struct { const framed = u.faded(std.math.clamp((t - p.work) / Plan.row, 0, 1)); framed.text(.sans, theme.size.sans.micro, bytes_x, body.y + 22, if (std.mem.indexOfScalar(u8, signature, 's') != null) "the path it was given" else "the bytes it was given", k.dim); const shown = @min(made.text.len, shown_bytes); + const text = for (made.text[0..shown]) |byte| { + if (!std.ascii.isPrint(byte) and byte != '\n') break false; + } else true; for (made.text[0..shown], 0..) |byte, j| { const cell: Rect = .{ .x = bytes_x + @as(f32, @floatFromInt(j % per_row)) * 28, .y = body.y + 32 + @as(f32, @floatFromInt(j / per_row)) * 30, .w = 26, .h = 26 }; // Each fills as it is copied, two frames a byte: struck, then held. @@ -285,7 +318,10 @@ pub const Crossing = struct { u.fill(cell, ui.mix(theme.color.kernel, ui.mix(theme.mark(.write).solid, k.held, std.math.clamp((since - theme.time.quick) / theme.time.strike.cool, 0, 1)), in)); u.frame(cell, k.ink, theme.stroke.rule); if (in < 0.5) continue; - if (std.ascii.isPrint(byte) and byte != ' ') u.label(.mono, size, cell, .center, &.{byte}, k.ink) else if (byte == '\n') u.label(.mono, size, cell, .center, "\\n", k.dim); + // Text as its characters; anything else (a page of a file) as hex. + if (!text) { + u.label(.mono, size, cell, .center, u.print("{x:0>2}", .{byte}), k.ink); + } else if (std.ascii.isPrint(byte) and byte != ' ') u.label(.mono, size, cell, .center, &.{byte}, k.ink) else if (byte == '\n') u.label(.mono, size, cell, .center, "\\n", k.dim); } } @@ -321,16 +357,10 @@ pub const Crossing = struct { } }; -/// What an argument is called: by the call's own names where they are -/// known, else from its letter in `zt.syscalls.signature`. -/// shortcut: four calls named; the recorder's table should carry every call's argument names. +/// What an argument is called: by the call's own names where the tracer's +/// table has them, else from its letter in `zt.syscalls.signature`. fn what(nr: u16, kind: u8, arg: usize) []const u8 { - const names: []const []const u8 = switch (std.enums.fromInt(std.os.linux.SYS, nr) orelse .restart_syscall) { - .open => &.{ "path", "flags", "mode" }, - .read, .write => &.{ "fd", "buf", "count" }, - .close => &.{"fd"}, - else => &.{}, - }; + const names = zt.syscalls.names(nr); if (arg < names.len) return names[arg]; return switch (kind) { 'i' => "number", @@ -421,12 +451,12 @@ pub const Timeline = struct { }; test "a crossing is as long as what the call does" { - // A call with no work: 4.0 s. Fifteen bytes copied up: 5.1. - try std.testing.expectApproxEqAbs(@as(f32, 4.00), Plan.of(.{ .nr = 3, .args = @splat(0), .enter = 0 }).total, 1e-3); + // A call with no work: 4.1 s. Fifteen bytes copied up: 5.2. + try std.testing.expectApproxEqAbs(@as(f32, 4.10), Plan.of(.{ .nr = 3, .args = @splat(0), .enter = 0 }).total, 1e-3); const read = Plan.of(.{ .nr = 0, .args = .{ 3, 0x1000, 32, 0, 0, 0 }, .enter = 0, .exit = 0, .result = 15 }); - try std.testing.expectApproxEqAbs(@as(f32, 5.07), read.total, 1e-2); - // What came back is stored after it came back. - try std.testing.expect(read.stored > read.returns); + try std.testing.expectApproxEqAbs(@as(f32, 5.17), read.total, 1e-2); + // What came back is read in the kernel's rows, then struck in rax, then stored. + try std.testing.expect(read.struck >= read.returns + theme.time.strike.arm and read.stored > read.struck); // Nothing on the kernel's side before the arrow is through the line. try std.testing.expect(read.leaves >= read.enters and read.name >= read.enters + Plan.cross); try std.testing.expect(read.fills > read.name and read.returns > read.fills + 15 * Plan.byte); -- cgit v1.3