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/hexdump.zig | 276 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 272 insertions(+), 4 deletions(-) (limited to 'anim/src/hexdump.zig') diff --git a/anim/src/hexdump.zig b/anim/src/hexdump.zig index bd76150..b98d9bd 100644 --- a/anim/src/hexdump.zig +++ b/anim/src/hexdump.zig @@ -79,6 +79,52 @@ pub fn panel(f: *@import("sketch").Frame, placed: @import("anim").Placed, stage: return .{ .u = u, .rows = theme.layout.rowsIn(box.h), .box = box }; } +/// A view of a region the scene names (`of`), by its fields: the band's +/// right half, over the state column. The scene marks fields as read +/// (`marks`, a value each: how much the frame shows). In a step that hands +/// the region to the kernel (a write's buffer), its fields are framed as +/// read while the kernel takes them, and the bytes the recording had not +/// seen come in from the call's capture, dots to digits, with no mark. +pub const Dump = struct { + cursor: cursors.Cursor, + stage: *const @import("stage.zig").Stage, + /// The tag's words, after `its bytes`; and the legend of its fields. + about: []const u8, + legend: []const ui.Legend = &.{}, + of: Fields, + marks: []const @import("anim").Value = &.{}, + + pub fn draw(d: *const Dump, f: *@import("sketch").Frame, placed: @import("anim").Placed) void { + const v = panel(f, placed, d.stage, d.about, d.legend); + defer v.u.unclip(); + if (v.rows == 0) return; + const now = d.cursor.now(placed); + var of = d.of; + var shows: [8]f32 = @splat(0); + const marked = @min(d.marks.len, shows.len); + for (d.marks[0..marked], shows[0..marked]) |mark, *value| value.* = placed.value(mark); + of.marks = shows[0..marked]; + // A call the step made that was given these bytes: as the kernel + // took them, from when its work begins (and at the stop after it; + // a step later the program may have written them again). + const syscalls = @import("syscalls.zig"); + for (d.cursor.rec.syscalls) |made| { + if (made.enter <= now.stops[1] or made.enter > now.stops[0]) continue; + const span = syscalls.bufferRead(made) orelse continue; + if (span.addr >= of.base + of.len or span.addr + span.len <= of.base) continue; + var shown: f32 = 1; + if (!now.resting()) { + const p = syscalls.Plan.of(made); + shown = std.math.clamp((now.time - p.work) / theme.time.quick, 0, 1); + of.read = now.held(p.work); + } + of.given = .{ .addr = span.addr, .bytes = made.text[0..@min(made.text.len, span.len)], .shows = shown }; + } + fielded(v, now, m.tag + m.pad, of); + v.veil(now); + } +}; + /// The view's panel as drawn: its `Ui`, how many rows it holds, its box. pub const View = struct { u: ui.Ui, @@ -140,14 +186,14 @@ pub fn draw(u: ui.Ui, now: cursors.Now, x: f32, y: f32, first: u64, count: usize at += run.len; } rows.bytes(v, ry, addr, &values, &known, runs[0..n], of.region, lead, holds_drawn, moment); - reading(v, ry, moment, &values, &known, runs[0..n]); + reading(v, ry, addr, moment, &values, &known, runs[0..n]); } } /// The reading: what the runs read as, little-endian. A number ranged /// right in three characters; a pointer as `points` and its address; /// `NULL` dim; an allocator's run as a note, faint. -fn reading(u: ui.Ui, y: f32, moment: Recording.Moment, values: *const [16]u8, known: *const [16]bool, runs: []const rows.Run) void { +fn reading(u: ui.Ui, y: f32, addr: u64, moment: Recording.Moment, values: *const [16]u8, known: *const [16]bool, runs: []const rows.Run) void { const size = theme.size.mono.context; const base = rows.baseline(y); var x: f32 = b.reading; @@ -173,12 +219,234 @@ fn reading(u: ui.Ui, y: f32, moment: Recording.Moment, values: *const [16]u8, kn x = u.arrow(x, y + m.row / 2, .points); x = u.address(x, base, word, .{ .ink = ui.rgb(rows.ink(rows.regionOf(moment, word))) }) + 8; }, - .allocator => if (run.first == 8 and run.len == 8) { + .allocator => if (run.first == 8 and run.len == 8 and chunkAfter(moment, addr + 8)) { // The size word of the chunk after: malloc's. u.text(.sans, theme.size.sans.micro, x, base - 1, u.print("malloc's: a chunk of {d}", .{word & ~@as(u64, 7)}), t.faint); return; }, - .unread => {}, + .text, .unread => {}, + } + } +} + +/// Whether an allocation the recording has begins just after the word at +/// `word` (the chunk's size word, glibc's and musl's alike): only there are +/// bytes between allocations the allocator's own, to be read as its. +fn chunkAfter(moment: Recording.Moment, word: u64) bool { + const a = (moment.allocation(word + 8) catch return false) orelse return false; + return a.ptr == word + 8; +} + +/// What a field of a region reads as: a number (little-endian, or `big`), +/// a pointer, text (in quotes, C's escapes), or bytes the reading leaves +/// to the eye. +pub const Reads = enum { number, pointer, text, bytes }; + +/// A field of the region a view is about, from the region's first byte. +pub const Field = struct { + at: u64, + len: u64, + reads: Reads = .number, + /// Stored high byte first (SQLite's pages are). + big: bool = false, + /// Which of the view's marks frames it as read (`Fields.marks`). + mark: ?u8 = null, +}; + +/// What a dump of fields is of, and how it is marked now. +pub const Fields = struct { + /// The region: where it begins, how long it is, the ink of its memory. + base: u64, + len: u64, + fields: []const Field, + region: u24 = theme.color.region.heap, + /// How much each of the view's marks shows (a frame, read's colour). + marks: []const f32 = &.{}, + /// Bytes known from elsewhere than the moment's memory (what a syscall + /// was given, as the kernel took them), and how much they show (0 to 1). + given: ?struct { addr: u64, bytes: []const u8, shows: f32 } = null, + /// How much a frame round every field shows: the kernel reading them. + read: f32 = 0, + /// The part of the region the recording read at the stop shown (null: + /// all of it as last seen). Memory nothing watches is read only where a + /// pointer leads, 32 bytes at a stop; elsewhere its last seen bytes may + /// be long out of date, and are drawn as not seen. + seen: ?Recording.Span = null, +}; + +/// The region's rows in view `v`, from `y`, sixteen bytes a row from its +/// first byte: those that hold a field (all of them, where they fit), and +/// for a stretch left out one row of `more`'s dots and how many rows it +/// stands for. A field is a run, cut where a row ends; a byte that is no +/// field is drawn as the allocator's (dim, no paper) and reads as nothing. +pub fn fielded(v: View, now: cursors.Now, y: f32, of: Fields) void { + const u = v.u; + const moment = now.shown(.memory); + const total = (of.len + 15) / 16; + var shown: [16]u64 = undefined; + var n: usize = 0; + for (0..total) |r| { + const lo = of.base + 16 * r; + const holds = for (of.fields) |field| { + if (of.base + field.at < lo + 16 and of.base + field.at + field.len > lo) break true; + } else false; + if ((holds or total <= v.rows) and n < shown.len) { + shown[n] = r; + n += 1; + } + } + const lead = ui.shared(&.{ of.base, of.base + 16 * (total -| 1) }); + var ry = y; + var last: ?u64 = null; + for (shown[0..n]) |r| { + if (last) |l| if (r > l + 1) { + // A stretch left out: one row, three dots and a count. + const after = u.arrow(b.address, ry + m.row / 2, .more); + u.text(.mono, theme.size.mono.context, after + adv, rows.baseline(ry), u.print("{d} rows", .{r - l - 1}), t.faint); + ry += m.row; + }; + last = r; + fieldRow(u, now, ry, of.base + 16 * r, moment, of, lead); + ry += m.row; + } +} + +fn fieldRow(u: ui.Ui, now: cursors.Now, y: f32, addr: u64, moment: Recording.Moment, of: Fields, lead: usize) void { + var values: [16]u8 = undefined; + var known: [16]bool = undefined; + moment.read(addr, &values, &known) catch return; + if (of.seen) |seen| for (&known, 0..) |*k, i| { + if (addr + i < seen.addr or addr + i >= seen.addr + seen.len) k.* = false; + }; + // What a call was given is as the kernel took it, and not what the + // recording saw there before (a debugger reads a buffer it is not + // watching only where a pointer leads, 32 bytes at a stop: the rest + // is as it was when last seen): it comes in over what was drawn. + var given_values = values; + var given_known = known; + var gives = false; + var given_from: u8 = 16; + var given_to: u8 = 0; + if (of.given) |g| for (0..16) |i| { + const a = addr + i; + if (a < g.addr or a >= g.addr + g.bytes.len) continue; + given_values[i] = g.bytes[a - g.addr]; + given_known[i] = true; + gives = true; + given_from = @min(given_from, @as(u8, @intCast(i))); + given_to = @max(given_to, @as(u8, @intCast(i))); + }; + const shift = rows.addressRoom(addr); + var runs: [16]rows.Run = undefined; + var readings: [16]Field = undefined; + var n: usize = 0; + var at: u8 = 0; + while (at < 16 and addr + at < of.base + of.len) { + const here = addr + at; + const field = for (of.fields) |field| { + if (of.base + field.at <= here and here < of.base + field.at + field.len) break field; + } else null; + var run: rows.Run = .{ .first = at, .len = 1, .kind = .allocator }; + if (field) |fl| { + run.len = @intCast(@min(of.base + fl.at + fl.len - here, 16 - @as(u64, at))); + run.kind = switch (fl.reads) { + .number, .bytes => .number, + .pointer => .pointer, + .text => .text, + }; + run.heat = now.written(here, run.len, .memory, 0); + var framed: f32 = 0; + if (fl.mark) |k| if (k < of.marks.len) { + framed = of.marks[k]; + }; + if (now.wasRead(here, run.len) and now.writeAge(here, run.len) != 0) framed = @max(framed, now.reading(.memory, 0)); + run.read = framed; + readings[n] = .{ .at = at, .len = run.len, .reads = fl.reads, .big = fl.big }; + ties.anchor(u, .{ .dump_run = here }, .{ .x = shift + rows.byteX(run.first) - 4, .y = y, .w = rows.byteX(run.first + run.len - 1) + 28 - rows.byteX(run.first) + 4, .h = m.row }); + } else { + // Up to the next field, or the row's end. + var end: u64 = @min(16, of.base + of.len - addr); + for (of.fields) |other| if (of.base + other.at > here and of.base + other.at < addr + end) { + end = of.base + other.at - addr; + }; + run.len = @intCast(end - at); + readings[n] = .{ .at = at, .len = run.len, .reads = .bytes }; + } + runs[n] = run; + n += 1; + at += run.len; + } + // The kernel reading them: one frame round what it took of the row. + if (gives and of.read > 0) u.faded(of.read).frame(.{ .x = shift + rows.byteX(given_from) - 7, .y = y - 1, .w = rows.byteX(given_to) - rows.byteX(given_from) + 38, .h = m.row + 2 }, theme.mark(.read).solid, 2); + const shows = if (of.given) |g| g.shows else 0; + if (gives and shows > 0) { + if (shows < 1) rows.bytesAt(u.faded(1 - shows), y, addr, &values, &known, runs[0..n], of.region, lead, true, moment, shift); + rows.bytesAt(u.faded(shows), y, addr, &given_values, &given_known, runs[0..n], of.region, lead, true, moment, shift); + fieldReading(u.faded(shows), y, shift, moment, &given_values, &given_known, readings[0..n]); + } else { + rows.bytesAt(u, y, addr, &values, &known, runs[0..n], of.region, lead, true, moment, shift); + fieldReading(u, y, shift, moment, &values, &known, readings[0..n]); + } +} + +/// The reading of a row of fields, left to right, a character apart: a +/// number in decimal, a pointer as `points` and its address, text in +/// quotes; bytes left to the eye read as nothing. Cut where the panel +/// ends, with `…`. +fn fieldReading(u: ui.Ui, y: f32, shift: f32, moment: Recording.Moment, values: *const [16]u8, known: *const [16]bool, fields: []const Field) void { + const size = theme.size.mono.context; + const base = rows.baseline(y); + const room = theme.layout.state.w - theme.metric.context.side; + var x: f32 = b.reading + shift; + for (fields) |fl| { + const first: usize = @intCast(fl.at); + const len: usize = @intCast(fl.len); + if (fl.reads == .bytes) continue; + if (std.mem.indexOfScalar(bool, known[first..][0..len], false) != null) continue; + const bytes = values[first..][0..len]; + const words: []const u8 = switch (fl.reads) { + .number => blk: { + var word: u64 = 0; + for (0..@min(len, 8)) |k| word |= @as(u64, bytes[if (fl.big) len - 1 - k else k]) << @intCast(8 * k); + break :blk u.print("{d}", .{word}); + }, + .pointer => blk: { + var word: u64 = 0; + for (0..@min(len, 8)) |k| word |= @as(u64, bytes[k]) << @intCast(8 * k); + if (word == 0) break :blk "NULL"; + if (x + theme.metric.context.arrow_w + @as(f32, @floatFromInt(ui.digits(word))) * adv > room) break :blk "\u{2026}"; + x = u.arrow(x, y + m.row / 2, .points); + x = u.address(x, base, word, .{ .ink = ui.rgb(rows.ink(rows.regionOf(moment, word))) }) + adv; + continue; + }, + .text => quoted(u, bytes), + .bytes => unreachable, + }; + const w = u.width(.mono, size, words); + const fits = x + w <= room; + const shown = if (fits) words else rows.fitted(u, words, room - x); + const ink = if (fl.reads == .text) theme.color.string else if (std.mem.eql(u8, words, "NULL")) t.dim else t.primary; + u.text(.mono, size, x, base, shown, ink); + if (!fits) return; + x += w + adv; + } +} + +/// Bytes as C text, in quotes: the printable as they are, the rest by C's +/// escapes; a NUL ends it. +fn quoted(u: ui.Ui, bytes: []const u8) []const u8 { + const a = u.f.scratch; + var out: std.ArrayList(u8) = .empty; + out.append(a, '"') catch return ""; + for (bytes) |c| { + if (c == 0) break; + switch (c) { + '\n' => out.appendSlice(a, "\\n") catch {}, + '\t' => out.appendSlice(a, "\\t") catch {}, + '"', '\\' => out.appendSlice(a, &.{ '\\', c }) catch {}, + else => if (std.ascii.isPrint(c)) out.append(a, c) catch {} else out.print(a, "\\x{x:0>2}", .{c}) catch {}, } } + out.append(a, '"') catch {}; + return out.items; } -- cgit v1.3