diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 16:05:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 16:43:58 -0300 |
| commit | 165bb6c1344b98de7bef1d3c2b72147b4a40797a (patch) | |
| tree | 0e70e6222700063f604f78673f6ab3a5bfb9242d /anim/src/hexdump.zig | |
| parent | 66a2a7cf733f6abc1f79561c52d901ce67019fb1 (diff) | |
| download | computeranim-165bb6c1344b98de7bef1d3c2b72147b4a40797a.tar.gz computeranim-165bb6c1344b98de7bef1d3c2b72147b4a40797a.zip | |
canim: the renderer speaks the design language
The blocks, their states and the tokens carry the catalogue's names:
atoms in ui, chain/reg/slot in rows, insn with its line column, jump lane
and annotations (read, write, taken or not, a call with its arguments, a
return, a syscall) in disasm, bytes and hexdump with field paper and the
reading column, the three splits and relayout in stage, the ties (thread,
link and pin, projection, echo). A lens is a band over the whole context,
its drawing left and its bytes right. Frames' spans on the stack, each
instruction's line and a callee's parameter count come from the tracer.
A gallery scene draws every block; the test compares six of its pages
with pictures kept in test/gallery, drawn from a recording kept there
too. The scenes are ported; the motion checks report no pop and no
metronome in any of them.
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'anim/src/hexdump.zig')
| -rw-r--r-- | anim/src/hexdump.zig | 233 |
1 files changed, 138 insertions, 95 deletions
diff --git a/anim/src/hexdump.zig b/anim/src/hexdump.zig index e4b0908..165f241 100644 --- a/anim/src/hexdump.zig +++ b/anim/src/hexdump.zig @@ -1,114 +1,157 @@ -//! Memory as a hexdump, for a lens that shows what its idea is made of: an -//! address gutter, sixteen bytes a row, the same bytes as text; and every -//! run of bytes marked as what it is, from the types of what the program's -//! pointers reach: a struct's number plain, its pointer in the ink of -//! where it points, the allocator's own bytes between allocations faint, -//! bytes never observed two dots. A line under a run says which field it -//! is (the legend is in the tag). Bytes a step wrote are struck here a -//! beat before the idea drawn from them changes: the words are the cause. -//! Reads `Moment.read` (with what is known), `Moment.allocation`, and the -//! recording's types. +//! `hexdump` (design/README.md, "3. Panels"): memory as `bytes` rows, +//! sixteen a row, the right half of a lens: the pane its drawing is a view +//! of. A window of the region kept round the rows the step touches (five +//! beside, nine as the subject), in address order; a gap in the addresses +//! is one row of `more`'s dots and the count left out. Each row's runs +//! come from the types of what the program's pointers reach: a field's +//! bytes on raised paper in its ink, the allocator's dim, never read two +//! dots; and its reading at 640: what the runs read as, little-endian. +//! Bytes a step wrote are struck here before the drawing reacts. +//! Reads `Moment.read`, `Moment.allocation`, and the recording's types. const std = @import("std"); -const sk = @import("sketch"); -const anim = @import("anim"); const ui = @import("ui.zig"); +const rows = @import("rows.zig"); const cursors = @import("cursor.zig"); -const contexts = @import("context.zig"); const Recording = @import("Recording.zig"); const objects = @import("objects.zig"); +const ties = @import("ties.zig"); const theme = ui.theme; const Rect = ui.Rect; const t = theme.color.text; const m = theme.metric.context; -const size = theme.size.mono.context; -const adv = size * 3 / 5; -/// A byte's two digits, and the gap to the next; a wider one in the middle of a row. -const pitch = 28; -const middle = 12; +const b = theme.metric.bytes; +const adv = theme.size.mono.context * 3 / 5; -pub const Hexdump = struct { - cursor: cursors.Cursor, - box: Rect, - title: []const u8 = "heap", - /// The first row's address; rounded down to sixteen. - base: u64, - focus: bool = false, +/// What a word of the region is. +pub const Kind = enum { number, pointer, allocator, unread }; - const Kind = enum { number, pointer, allocated, allocator, unknown }; +/// The kind of the word at `addr`: a field of a struct the program's +/// pointers reach (by its type), other allocated bytes, the allocator's +/// own between allocations, or never observed. +pub fn kindOf(things: []const objects.Object, moment: Recording.Moment, addr: u64) Kind { + for (things) |o| { + if (!o.holds(addr)) continue; + for (o.type.record.fields) |field| if (o.addr + field.offset == addr) return if (field.type == .pointer) .pointer else .number; + return .number; + } + var bytes: [8]u8 = undefined; + var known: [8]bool = undefined; + moment.read(addr, &bytes, &known) catch return .unread; + if (std.mem.indexOfScalar(bool, &known, true) == null) return .unread; + return if ((moment.allocation(addr) catch null) != null) .number else .allocator; +} + +/// The rows of a region (`lo .. hi`, sixteen-aligned) a dump of `count` +/// rows shows: all of them, or a window round the first the step touched. +pub fn window(now: cursors.Now, lo: u64, hi: u64, count: usize) u64 { + const all = (hi - lo) / 16; + if (all <= count) return lo; + var touched: ?u64 = null; + for ([_][]const Recording.Span{ now.rec.written(now.stops[1], now.stops[0]), now.rec.read(now.stops[1], now.stops[0]) }) |spans| for (spans) |span| { + if (touched == null and span.addr >= lo and span.addr < hi) touched = span.addr & ~@as(u64, 15); + }; + const at = touched orelse lo; + const row = (at - lo) / 16; + const first = @min(row -| (count / 2), all - count); + return lo + first * 16; +} + +/// What a dump is of: the structs a drawing beside it draws, or an array +/// of numbers (an element a run), and the ink of the memory it is in. +pub const Of = struct { + things: []const objects.Object = &.{}, + array: ?struct { addr: u64, len: u64, elem: u8 } = null, + region: u24 = theme.color.region.heap, +}; - pub fn draw(g: *const Hexdump, f: *sk.Frame, at: anim.Placed) void { - const u: ui.Ui = .{ .f = f, .at = at }; - const now = g.cursor.now(at); - const rec = g.cursor.rec; - const body = u.panel(g.box.w, g.box.h, g.title, .{ .focus = g.focus, .note = "sixteen bytes a row \u{00b7} underlined: a field of a node; faint: the allocator's own" }); - const things = objects.reach(f.scratch, rec, now.moment(), null); - const rows: usize = @intFromFloat(@floor((body.h - 2 * m.pad) / m.row)); - const bytes_x = m.side + 14 * adv + 8; - const text_x = bytes_x + 16 * pitch + middle + 12; - for (0..rows) |row| { - const addr = (g.base & ~@as(u64, 15)) + row * 16; - const y = body.y + m.pad + @as(f32, @floatFromInt(row)) * m.row; - const base = theme.baseline(y, m.row, size); - _ = u.value(m.side, base, addr, true, .{ .ink = ui.rgb(contexts.ink(contexts.regionOf(now.moment(), addr))) }); - var is: [16]u8 = undefined; - var known: [16]bool = undefined; - now.moment().read(addr, &is, &known) catch return; - var was: [16]u8 = undefined; - var was_known: [16]bool = undefined; - now.before().read(addr, &was, &was_known) catch return; - // A word at a time: a mark, and a field's line, go under a run of bytes, not under each. - for (0..2) |half| { - const word = addr + half * 8; - const x = bytes_x + @as(f32, @floatFromInt(half)) * (8 * pitch + middle); - const span: Rect = .{ .x = x - 3, .y = y + 2, .w = 8 * pitch - 4 + 2, .h = m.row - 4 }; - @import("ties.zig").anchor(u, .{ .word = word }, span); - const landed = now.landed(.memory, 0); - const mark = u.struck(span, now.written(word, 8, .memory, 0)); - if (now.wasRead(word, 8) and now.writeAge(word, 8) != 0) u.readFrame(span, now.reading(.memory, 0)); - const kind = g.kindOf(things, now.moment(), word); - // What the eight bytes are, if they are an address: its ink. - const held = Recording.word(if (landed) now.moment() else now.before(), word, 8) catch null; - const region = if (held) |value| contexts.regionOf(now.moment(), value) else .none; - const color: ui.Color = if (mark) |struck| struck.ink else switch (kind) { - .pointer => if (region != .none) ui.rgb(contexts.ink(region)) else ui.rgb(t.dim), - .number => ui.rgb(t.primary), - .allocated => ui.rgb(t.dim), - .allocator, .unknown => ui.rgb(t.faint), +/// The dump: `count` rows from `first`, at `x` (its panel's left edge +/// is the band's middle), the rows from `y`. The rows of what the drawing +/// draws have quiet brackets. +pub fn draw(u: ui.Ui, now: cursors.Now, x: f32, y: f32, first: u64, count: usize, of: Of) void { + const v = u.moved(x, 0); + const moment = now.shown(.memory); + const lead = ui.shared(&.{ first, first + 16 * @as(u64, count -| 1) }); + for (0..count) |i| { + const addr = first + 16 * i; + const ry = y + @as(f32, @floatFromInt(i)) * m.row; + var values: [16]u8 = undefined; + var known: [16]bool = undefined; + moment.read(addr, &values, &known) catch return; + var runs: [16]rows.Run = undefined; + var n: usize = 0; + var holds_drawn = false; + var at: u64 = 0; + while (at < 16) { + const here = addr + at; + var run: rows.Run = .{ .first = @intCast(at), .len = 8, .kind = .unread }; + if (of.array) |arr| if (here >= arr.addr and here < arr.addr + arr.len) { + run.len = arr.elem; + run.kind = .number; + holds_drawn = true; + }; + if (run.kind == .unread) { + // A word, or what is left of one before an array begins. + run.len = @intCast(@min(8 - (here % 8), 16 - at)); + if (of.array) |arr| if (here < arr.addr and arr.addr < here + run.len) { + run.len = @intCast(arr.addr - here); + }; + run.kind = switch (kindOf(of.things, moment, here)) { + .number => .number, + .pointer => .pointer, + .allocator => .allocator, + .unread => .unread, + }; + for (of.things) |o| if (o.holds(here)) { + holds_drawn = true; }; - for (0..8) |i| { - const n = half * 8 + i; - const bx = x + @as(f32, @floatFromInt(i)) * pitch; - if (!(if (landed) known[n] else was_known[n])) { - u.unknown(.{ .x = bx, .y = y, .w = 2 * adv, .h = m.row }); - continue; - } - const byte = if (landed) is[n] else was[n]; - u.text(if (mark != null) .mono_bold else .mono, size, bx, base, u.print("{x:0>2}", .{byte}), color); - // The same byte as text. - const tx = text_x + @as(f32, @floatFromInt(n)) * adv; - if (std.ascii.isPrint(byte) and byte != ' ') u.text(.mono, size, tx, base, &.{byte}, t.dim) else u.fill(.{ .x = tx + 4, .y = y + m.row / 2 - 2, .w = 4, .h = 4 }, t.faint); - } - // Which field: a line under the run, in the field's ink. - if (kind == .number or kind == .pointer) u.fill(.{ .x = x, .y = y + m.row - 3, .w = 8 * pitch - 4, .h = theme.stroke.rule }, if (kind == .pointer) theme.color.region.heap else t.primary); } + run.heat = now.written(here, run.len, .memory, 0); + if (now.wasRead(here, run.len) and now.writeAge(here, run.len) != 0) run.read = now.reading(.memory, 0); + if (run.kind == .number or run.kind == .pointer) ties.anchor(v, .{ .dump_run = here }, .{ .x = rows.byteX(run.first) - 4, .y = ry, .w = rows.byteX(run.first + run.len - 1) + 28 - rows.byteX(run.first) + 4, .h = m.row }); + runs[n] = run; + n += 1; + at += run.len; } - u.veil(.{ .x = theme.stroke.rule, .y = body.y, .w = body.w - 2 * theme.stroke.rule, .h = body.h - theme.stroke.rule }, now.veil); + 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]); } +} - /// What the word at `addr` is: a field of a struct the program's - /// pointers reach (by its type), other allocated bytes, the - /// allocator's own between allocations, or never observed. - fn kindOf(g: *const Hexdump, things: []const objects.Object, moment: Recording.Moment, addr: u64) Kind { - _ = g; - for (things) |o| { - if (!o.holds(addr)) continue; - for (o.type.record.fields) |field| if (o.addr + field.offset == addr) return if (field.type == .pointer) .pointer else .number; - return .allocated; +/// 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 { + const size = theme.size.mono.context; + const base = rows.baseline(y); + var x: f32 = b.reading; + for (runs) |run| { + var bytes: [8]u8 = @splat(0); + @memcpy(bytes[0..run.len], values[run.first..][0..run.len]); + const word = std.mem.readInt(u64, &bytes, .little); + const whole = std.mem.indexOfScalar(bool, known[run.first..][0..run.len], false) == null; + if (!whole) continue; + switch (run.kind) { + .number => { + // A field typed a number reads as its decimal. + const shift: u6 = @intCast(64 - 8 * @as(u32, @min(run.len, 8))); + const digits = u.print("{d}", .{@as(i64, @bitCast(word << shift)) >> shift}); + const w = @as(f32, @floatFromInt(digits.len)) * adv; + u.text(.mono, size, x + @max(3 * adv - w, 0), base, digits, t.primary); + x += @max(3 * adv, w) + 8; + }, + .pointer => if (word == 0) { + u.text(.mono, size, x + theme.metric.context.arrow_w, base, "NULL", t.dim); + x += theme.metric.context.arrow_w + 4 * adv + 8; + } else { + 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) { + // 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 => {}, } - var bytes: [8]u8 = undefined; - var known: [8]bool = undefined; - moment.read(addr, &bytes, &known) catch return .unknown; - if (std.mem.indexOfScalar(bool, &known, true) == null) return .unknown; - return if ((moment.allocation(addr) catch null) != null) .allocated else .allocator; } -}; +} |
