summaryrefslogtreecommitdiff
path: root/anim/src/syscalls.zig
diff options
context:
space:
mode:
Diffstat (limited to 'anim/src/syscalls.zig')
-rw-r--r--anim/src/syscalls.zig382
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);
+}