diff options
Diffstat (limited to 'anim/src/syscalls.zig')
| -rw-r--r-- | anim/src/syscalls.zig | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/anim/src/syscalls.zig b/anim/src/syscalls.zig new file mode 100644 index 0000000..9136ebb --- /dev/null +++ b/anim/src/syscalls.zig @@ -0,0 +1,382 @@ +//! The other side of a system call. `Crossing` is the kernel as a lens, +//! on solid vellum: the call the current +//! step made, decoded (its name, each argument in the register that +//! carried it, what it pointed at, and what came back in rax), the calls +//! before it, and the arrow that crosses the line and returns. `Timeline` +//! is the same boundary from far away: every call of the run as a block +//! under the line, the current one in gold. +//! Both read the recording's index of `syscall_enter` and `syscall_exit`. +const std = @import("std"); +const sk = @import("sketch"); +const anim = @import("anim"); +const zt = @import("ztrace"); +const ui = @import("ui.zig"); +const cursors = @import("cursor.zig"); +const Recording = @import("Recording.zig"); +const theme = ui.theme; +const time = theme.time; +const Rect = ui.Rect; +const k = theme.color.on_kernel; + +/// A crossing's timetable, in seconds into its step (design/motion.md, "A +/// system call"). Staging, one thing at a time and no effect before its +/// cause: the line fires; the registers that carry the call are framed, +/// one by one; the arrow goes down through the line; only then does the +/// 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` 3.7 s, a `read` of +/// fifteen bytes 4.8. +pub const Plan = struct { + registers: f32 = time.cascade, + enters: f32 = 0.80, + /// The kernel's side: the last call out, this one's name in, its + /// rows (one every `row`), its card pushed. + leaves: f32 = 1.00, + name: f32 = 1.20, + rows: f32 = 1.40, + card: f32 = 1.70, + /// The work: a flow between the kernel and the program's bytes, then + /// the bytes, one every `byte`, `bytes` of them. + work: f32 = 2.00, + fills: f32 = 2.40, + bytes: f32 = 0, + /// The arrow back sets off; rax is struck; the mark moves on. + back: f32 = 2.00, + returns: f32 = 2.40, + advance: f32 = 3.10, + total: f32 = 3.70, + + pub const cross = 0.40; + pub const row = 0.10; + pub const byte = 2.0 / 60.0; + + pub fn of(call: Recording.Syscall) Plan { + var p: Plan = .{}; + // Down: the bytes it was given. Up: the bytes it wrote into the program. + const down: usize = @min(call.text.len, shown_bytes); + const up: u64 = if (fills(call)) |span| span.len else 0; + 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.advance = p.returns + row + time.read_value; + p.total = p.advance + time.step + time.rest; + return p; + } + + /// The same as the cursor's plan: the registers are the CPU's level, + /// the bytes memory's. + pub fn step(p: Plan) cursors.Plan { + return .{ .at = .{ p.registers, p.fills, p.fills }, .advance = p.advance, .travel = time.step, .total = p.total }; + } +}; + +/// How many of the bytes a call was given the kernel's side shows. +const shown_bytes = 2 * 11; + +/// One line of the program and the call into the kernel it makes, as one +/// step of the cursor, timed by the crossing. A line that makes no call +/// is walked like any other. +pub fn step(c: cursors.Cursor, s: *anim.Frame, by: Recording.Stop) void { + const from = c.moment(s); + const to = c.rec.next(by, from); + const made = for (c.rec.syscalls) |made| { + if (made.enter > from and made.enter <= to) break made; + } else return c.walk(s, by, to); + const p = Plan.of(made); + c.step(s, to, p.step(), p.total); +} + +/// The argument registers of a syscall, in order. +const carriers = [_][]const u8{ "rdi", "rsi", "rdx", "r10", "r8", "r9" }; + +/// The newest syscall entered by moment `i`. +pub fn latest(rec: *const Recording, i: u64) ?usize { + var found: ?usize = null; + for (rec.syscalls, 0..) |s, n| { + if (s.enter > i) break; + found = n; + } + return found; +} + +/// The syscall the cursor's step made (the newest, when it made several). +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]; + return if (call.enter > now.stops[1]) call else null; +} + +/// The registers that carried `call`'s arguments, in order. +pub fn carried(call: Recording.Syscall) []const []const u8 { + return carriers[0..@min(zt.syscalls.signature(call.nr).len, carriers.len)]; +} + +/// The bytes the kernel read from the program for `call`: the buffer of a +/// write. Null for a call that is given none. +pub fn bufferRead(call: Recording.Syscall) ?Recording.Span { + const signature = zt.syscalls.signature(call.nr); + const at = std.mem.indexOfScalar(u8, signature, 'b') orelse return null; + return .{ .addr = call.args[at], .len = call.args[at + 1] }; +} + +/// The bytes the kernel wrote into the program for `call`: what a read +/// put in its buffer. Null for a call that fills none. +/// shortcut: `read` alone; the recorder tells the bytes of any call, and a scene of `pread` or `recv` wants them named here. +pub fn fills(call: Recording.Syscall) ?Recording.Span { + const got: i64 = @bitCast(call.result); + return if (call.nr == @intFromEnum(std.os.linux.SYS.read) and got > 0) .{ .addr = call.args[1], .len = @intCast(got) } else null; +} + +/// The kernel as a lens: solid vellum, and nothing else on the frame is. +/// The call the step made, decoded (its name, a row an argument by the +/// argument's own name, what came back), the calls before it, the bytes it +/// was given; and the arrow that crosses into it from the registers' +/// side and returns. +pub const Crossing = struct { + cursor: cursors.Cursor, + box: Rect = theme.layout.split.beside.lens, + focus: bool = false, + + 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 { + const u: ui.Ui = .{ .f = f, .at = placed }; + const now = c.cursor.now(placed); + const rec = c.cursor.rec; + const body = u.panel(c.box.w, c.box.h, "kernel", .{ .focus = c.focus, .note = "the other side of a system call" }); + u.fill(.{ .x = theme.stroke.rule, .y = body.y, .w = body.w - 2 * theme.stroke.rule, .h = body.h - theme.stroke.rule }, theme.color.kernel); + 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 p = Plan.of(rec.syscalls[newest]); + const t: f32 = if (live) now.time else std.math.inf(f32); + if (t >= p.enters) c.arrows(u, body, t, p, rec.syscalls[newest]); + // No effect before its cause: until the arrow is through the + // line the kernel knows nothing of this call, and shows the last. + if (t < p.name) { + if (newest > 0) c.call(u.faded(1 - theme.ease(.exit, std.math.clamp((t - p.leaves) / (p.name - p.leaves), 0, 1))), body, rec.syscalls[newest - 1], .{}, std.math.inf(f32)); + } else c.call(u, body, rec.syscalls[newest], p, t); + + // The calls so far, newest on top. This one's row pushes in when + // the kernel has taken the call: the others make room first. + const pushed = cursors.standard(std.math.clamp((t - p.card) / theme.time.quick, 0, 1)); + const arrived = std.math.clamp((t - p.card - theme.time.snap) / theme.time.quick, 0, 1); + const top = body.y + 32; + var i = newest + 1; + while (i > 0) { + i -= 1; + const place = @as(f32, @floatFromInt(newest - i)) - (if (i == newest) 0 else 1 - pushed); + const y = top + place * (row_h + 4) - (if (i == newest) (1 - arrived) * 8 else 0); + if (y + row_h > body.y + body.h - 6) continue; + const v = if (i == newest) u.faded(arrived) else u; + const card: Rect = .{ .x = 12, .y = y, .w = 196, .h = row_h }; + const done = rec.syscalls[i]; + const gold = if (i == newest) arrived >= 1 else i + 1 == newest and arrived < 1; + if (gold) v.fill(card, theme.mark(.current).solid); + v.frame(card, k.ink, theme.stroke.rule); + const name = zt.syscalls.name(done.nr) orelse "?"; + v.text(if (gold) .mono_bold else .mono, size, card.x + 8, theme.baseline(card.y, card.h, size), name[0..@min(name.len, 11)], k.ink); + if ((i != newest or t >= p.returns + Plan.row) and done.exit != null) { + const words = result(u, done); + if (words.len <= 4) v.text(.mono, size, card.x + card.w - 8 - u.width(.mono, size, words), theme.baseline(card.y, card.h, size), words, k.dim); + } + } + } + + /// A call, decoded: its name, a row for each argument, what came + /// back; and to the right the bytes it was given, as the kernel + /// copies them. + fn call(c: *const Crossing, u: ui.Ui, body: Rect, made: Recording.Syscall, p: Plan, t: f32) void { + _ = c; + const x = 236; + const name = zt.syscalls.name(made.nr) orelse "syscall"; + // The name arrives rising, as a caption does. + const named = theme.ease(.enter, std.math.clamp((t - p.name) / theme.time.quick, 0, 1)); + const title = u.faded(named); + const rise = (1 - named) * theme.time.caption_rise; + title.text(.mono_bold, theme.size.mono.value, x, body.y + 46 + rise, name, k.ink); + title.text(.sans, theme.size.sans.micro, x + u.width(.mono_bold, theme.size.mono.value, name) + 16, body.y + 44 + rise, u.print("system call {d}", .{made.nr}), k.dim); + const signature = zt.syscalls.signature(made.nr); + var row_y: f32 = body.y + 62; + var text_used = false; + const row = struct { + fn draw(v: ui.Ui, y: f32, register: []const u8, meaning: []const u8, words: []const u8) void { + v.fill(.{ .x = x, .y = y, .w = 300, .h = theme.stroke.rule }, k.rule); + const base = theme.baseline(y, row_h + 4, size); + v.text(.mono, size, x, base, register, k.dim); + v.text(.sans_medium, theme.size.sans.tag, x + 52, base, meaning, k.ink); + v.text(.mono, size, x + 130, base, words, k.ink); + } + }.draw; + for (signature, 0..) |kind, arg| { + if (arg >= 4) break; + const shows = std.math.clamp((t - p.rows - @as(f32, @floatFromInt(arg)) * Plan.row) / Plan.row, 0, 1); + row(u.faded(shows), row_y, carriers[arg], what(made.nr, kind, arg), value(u, made, kind, arg, &text_used)); + row_y += row_h + 4; + } + const back = t >= p.returns + Plan.row and made.exit != null; + 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 (made.text.len == 0) return; + const bytes_x = 564; + 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); + for (made.text[0..shown], 0..) |byte, j| { + const cell: Rect = .{ .x = bytes_x + @as(f32, @floatFromInt(j % 11)) * 28, .y = body.y + 32 + @as(f32, @floatFromInt(j / 11)) * 30, .w = 26, .h = 26 }; + // Each fills as it is copied, two frames a byte: struck, then held. + const since = t - p.fills - @as(f32, @floatFromInt(j)) * Plan.byte; + if (since < 0) { + framed.frame(cell, k.rule, theme.stroke.rule); + continue; + } + const in = std.math.clamp(since / theme.time.strike.in, 0, 1); + 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); + } + } + + /// The crossing itself: in from the side the registers are on as the + /// call enters, and back out as it returns. Vellum outside the + /// kernel, ink inside it. Machines do not lob: straight. + fn arrows(c: *const Crossing, u: ui.Ui, body: Rect, t: f32, p: Plan, made: Recording.Syscall) void { + const edge = c.box.w; + // Off promptly, and settling in the kernel. + const down = cursors.standard(std.math.clamp((t - p.enters) / Plan.cross, 0, 1)); + const gone = std.math.clamp((t - p.returns - theme.time.quick) / theme.time.read.out, 0, 1); + const v = u.faded(1 - gone); + if (t < p.back) across(v, body.y + 190, edge + 26, edge + 26 - down * 86, edge); + if (made.exit != null and t > p.back) across(v, body.y + 226, edge - 60, edge - 60 + cursors.standard(std.math.clamp((t - p.back) / Plan.cross, 0, 1)) * 86, edge); + } + + /// An arrow along the row at `y` from `from` to `to`, in the colour of + /// the ground it is over: ink inside the kernel (left of `edge`), vellum outside. + fn across(u: ui.Ui, y: f32, from: f32, to: f32, edge: f32) void { + if (@abs(to - from) < 1) return; + const w = theme.stroke.arrow; + const head = theme.stroke.flow_head; + const dir: f32 = if (to > from) 1 else -1; + const neck = to - dir * (head[0] - 2); + const lo = @min(from, neck); + const hi = @max(from, neck); + if ((neck - from) * dir > 0) { + if (lo < edge) u.fill(.{ .x = lo, .y = y - w / 2, .w = @min(hi, edge) - lo, .h = w }, k.ink); + if (hi > edge) u.fill(.{ .x = @max(lo, edge), .y = y - w / 2, .w = hi - @max(lo, edge), .h = w }, theme.color.kernel); + } + if (@abs(to - from) < head[0]) return; + sk.draw.polygon(u.f, &.{ .{ to, y }, .{ to - dir * head[0], y - head[1] / 2 }, .{ to - dir * head[0], y + head[1] / 2 } }, u.at.pen(.{ .fill = if (to - dir * head[0] / 2 < edge) ui.rgb(k.ink) else ui.rgb(theme.color.kernel) })); + } +}; + +/// 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. +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 => &.{}, + }; + if (arg < names.len) return names[arg]; + return switch (kind) { + 'i' => "number", + 'd' => "size", + 's' => "path", + 'b' => "buffer", + else => "pointer", + }; +} + +fn value(u: ui.Ui, made: Recording.Syscall, kind: u8, arg: usize, text_used: *bool) []const u8 { + const a = made.args[arg]; + switch (kind) { + 'i' => return u.print("{d}", .{@as(i32, @bitCast(@as(u32, @truncate(a))))}), + 'd' => return u.print("{d}", .{a}), + 's' => if (made.text.len > 0 and !text_used.*) { + text_used.* = true; + const base = std.fs.path.basename(made.text); + return u.print("\"{s}\"", .{base[0..@min(base.len, 14)]}); + }, + else => {}, + } + return grouped(u, a); +} + +/// Hex in groups of four, as everywhere. +fn grouped(u: ui.Ui, n: u64) []const u8 { + return ui.grouped(u.f.scratch.alloc(u8, 20) catch return "?", n); +} + +/// What came back: a count, an address, or an error by name. +fn result(u: ui.Ui, made: Recording.Syscall) []const u8 { + const ret: i64 = @bitCast(made.result); + if (ret < 0 and ret > -4096) { + if (std.enums.fromInt(std.os.linux.E, -ret)) |e| return u.print("{d} E{t}", .{ ret, e }); + return u.print("{d}", .{ret}); + } + return if (ret > 0xffffff or ret < 0) grouped(u, made.result) else u.print("{d}", .{ret}); +} + +pub const Timeline = struct { + cursor: cursors.Cursor, + box: Rect, + focus: bool = false, + + pub fn draw(g: *const Timeline, 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 m = theme.metric.timeline; + const txt = theme.color.text; + const body = u.panel(g.box.w, g.box.h, "system calls", .{ .focus = g.focus, .note = "time runs right ยท a block is a call into the kernel" }); + const pad = theme.metric.panel.pad_x; + const line_y = body.y + @min(body.h / 2 - 24, 84); + u.text(.sans, theme.size.sans.note, pad, line_y - 14, "user", txt.dim); + u.text(.sans, theme.size.sans.note, pad, line_y + 32, "kernel", txt.dim); + u.fill(.{ .x = theme.stroke.rule, .y = line_y, .w = g.box.w - 2 * theme.stroke.rule, .h = m.baseline }, theme.color.kernel); + if (rec.syscalls.len == 0) return; + // shortcut: equal blocks; under ptrace a call's time is the tracer's, so widths would say nothing. + const room = g.box.w - 2 * pad - 110; + const apart = @min(96, room / @as(f32, @floatFromInt(rec.syscalls.len))); + const w = @max(m.min_block, apart - m.min_gap); + const current = latest(rec, now.stops[0]); + var last_name_end: f32 = 0; + for (rec.syscalls, 0..) |call, i| { + const x = pad + 110 + @as(f32, @floatFromInt(i)) * apart; + const block: Rect = .{ .x = x, .y = line_y + m.baseline, .w = w, .h = m.block_h }; + // Not yet made: hollow. + if (call.enter > now.stops[0]) u.frame(block, theme.color.rule, theme.stroke.rule) else u.fill(block, theme.color.kernel); + const name = zt.syscalls.name(call.nr) orelse "?"; + const name_w = u.width(.mono, theme.size.mono.small, name); + const here = current == i; + const name_x = x + w / 2 - name_w / 2; + const base = block.y + block.h + 34; + if (here) { + const gold = theme.mark(.current); + u.fill(.{ .x = x + w / 2 - m.now / 2, .y = line_y - 40, .w = m.now, .h = block.h + 52 }, gold.solid); + u.fill(.{ .x = name_x - 10, .y = base - 28, .w = name_w + 20, .h = 38 }, gold.solid); + u.text(.mono_bold, theme.size.mono.small, name_x, base, name, gold.on_solid); + last_name_end = name_x + name_w + 24; + } else if (name_x > last_name_end and (current == null or @abs(@as(f32, @floatFromInt(i)) - @as(f32, @floatFromInt(current.?))) * apart > name_w / 2 + 40)) { + // Names wherever one fits. + u.text(.mono, theme.size.mono.small, name_x, base, name, txt.dim); + last_name_end = name_x + name_w + 16; + } + } + } +}; + +test "a crossing is as long as what the call does" { + // A call with no work: 3.7 s. Fifteen bytes copied up: 4.8. + try std.testing.expectApproxEqAbs(@as(f32, 3.70), 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, 4.77), read.total, 1e-2); + // 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); +} |
