//! 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 rows = @import("rows.zig"); const cursors = @import("cursor.zig"); const Recording = @import("Recording.zig"); const context = @import("context.zig"); const hexdump = @import("hexdump.zig"); const Stage = @import("stage.zig").Stage; const theme = ui.theme; const time = theme.time; const Rect = ui.Rect; /// 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 kernel's rows say what it returns, the arrow comes /// back with it, and it strikes rax as the arrow lands. So a call is as /// long as what it does: `close` 3.9 s, a `read` of fifteen bytes 5.0. 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 `returns` row takes the value 6 f before the arrow back sets /// off (the kernel answers before the answer travels); rax is armed /// while the arrow travels and struck as it lands (nothing is marked as /// come back before it has); everything else the step changed waits /// for rax; the program stores what came back (memory, after its /// cause); the mark moves on. returns: f32 = 1.90, back: f32 = 2.00, struck: f32 = 2.40, stored: f32 = 2.70, advance: f32 = 3.30, total: f32 = 3.90, 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 - 6.0 / 60.0; p.struck = p.back + cross; p.stored = p.struck + time.cascade; p.advance = p.stored + 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.stored, p.stored }, .advance = p.advance, .travel = time.step, .total = p.total }; } }; /// How many of the bytes a call was given the kernel's side shows. /// Ten a row, two rows, in the drawing's 880 beside the arrows. const per_row = 10; const shown_bytes = 2 * per_row; /// 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); } /// 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" }; /// 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, 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; } /// 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 `syscalls` lens: the program's conversation with the kernel. Its /// drawing is the calls so far as strace writes them, a row each, oldest /// on top and the newest at the bottom (its row comes in once the call is /// back, with the turned corner); not the kernel, and not on vellum: the /// kernel is under the program, the floor of the disassembly's `descent`. /// Its view, the bytes the newest call was given or filled. 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 { 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)); // A relayout moves the band: what is drawn in it stays inside it. u.clip(.{ .x = 0, .y = 0, .w = box.w, .h = box.h }); defer u.unclip(); const now = c.cursor.now(placed); const rec = c.cursor.rec; const room = context.rowsOf(box); // The calls from the scene's first moment: the program's, not its loader's. var first: usize = 0; while (first < rec.syscalls.len and rec.syscalls[first].enter < c.cursor.first) first += 1; var newest = latest(rec, now.stops[0]); // A crossing's own row comes in once it is back (rax struck), 12 f. var arrives: f32 = 1; if (newest) |n| if (inStep(now) != null and now.walking()) { const p = Plan.of(rec.syscalls[n]); arrives = std.math.clamp((now.time - p.struck - 6.0 / 60.0) / theme.time.quick, 0, 1); }; if (newest) |n| if (n < first) { newest = null; }; const count = if (newest) |n| n + 1 - first else 0; const body = u.panel(box.w, box.h, "system calls", .{ .focus = c.focus, .note = if (count > room) u.print("as strace writes them \u{00b7} newest at the bottom \u{00b7} {d} more above", .{count - room}) else "as strace writes them \u{00b7} newest at the bottom" }); context.clipBody(u, box); defer u.unclip(); const n = newest orelse return; const top = body.y + theme.metric.context.pad; const shown = @min(count, room); for (0..shown) |j| { const i = n + 1 - shown + j; const v = if (i == n) u.faded(arrives) else u; const y = top + @as(f32, @floatFromInt(j)) * row_h; logRow(v, rec, rec.syscalls[i], y, box.w - theme.metric.context.side); if (i == n) v.corner(theme.metric.context.side, y + 2, theme.metric.context.corner, 1); } } /// A call as strace writes it, its arguments by name: `read fd 3 /// "note" buf 7fffffffecd0 count 32 = 15`, cut at `room` with `…`. fn logRow(u: ui.Ui, rec: *const Recording, made: Recording.Syscall, y: f32, room: f32) void { const base = theme.baseline(y, row_h, size); const adv = ui.advance(size); var x: f32 = theme.metric.context.side; const name = zt.syscalls.name(made.nr) orelse "syscall"; u.text(.mono_bold, size, x, base, name, theme.color.text.bright); x += u.width(.mono_bold, size, name) + adv; const names = zt.syscalls.names(made.nr); const n = @min(zt.syscalls.signature(made.nr).len, 6); const Part = struct { text: []const u8, ink: u24 }; var parts: [32]Part = undefined; var np: usize = 0; for (0..n) |j| { const what = if (j < names.len) names[j] else ""; if (what.len > 0) { parts[np] = .{ .text = what, .ink = theme.color.text.dim }; np += 1; } parts[np] = .{ .text = @import("disasm.zig").argument(u, rec, made.enter, what, made.args[j]), .ink = theme.color.text.primary }; np += 1; if (std.mem.endsWith(u8, what, "fd")) { const on = rec.openOn(u.f.scratch, made.args[j], made.enter); if (on.len > 0) { parts[np] = .{ .text = on, .ink = theme.color.text.faint }; np += 1; } } } parts[np] = .{ .text = "=", .ink = theme.color.text.faint }; np += 1; parts[np] = .{ .text = if (made.exit != null) result(u, made) else "?", .ink = theme.color.text.primary }; np += 1; for (parts[0..np]) |part| { const w = u.width(.mono, size, part.text); if (x + w > room) { u.text(.mono, size, x, base, "\u{2026}", theme.color.text.faint); return; } u.text(.mono, size, x, base, part.text, part.ink); x += w + adv; } } /// 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 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 (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; const path_at: ?usize = if (made) |given| std.mem.indexOfScalar(u8, zt.syscalls.signature(given.nr), 's') else null; const span: ?Recording.Span = if (made) |given| bufferRead(given) orelse fills(given) orelse if (given.text.len > 0 and path_at != null) .{ .addr = given.args[path_at.?], .len = given.text.len + 1 } else null else null; const scratch = context.at(f, placed, c.stage.box(placed, .view)); const about = if (span) |sp| scratch.print("the {s}, {x} to {x}", .{ if (bufferRead(made.?) != null) "buffer given" else if (fills(made.?) != null) "buffer filled" else "path given", sp.addr, sp.addr + sp.len - 1 }) else "the call names no bytes"; const v = hexdump.panel(f, placed, c.stage, about, &.{}); defer v.u.unclip(); const sp = span orelse return; if (v.rows == 0) return; // 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); } }; /// 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) u.print("{x}", .{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.9 s. Fifteen bytes copied up: 5.0. try std.testing.expectApproxEqAbs(@as(f32, 3.90), 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.97), read.total, 1e-2); // What came back is in the kernel's rows before the arrow back leaves, // struck in rax as it lands (armed on its way), then stored. try std.testing.expect(read.returns < read.back and read.struck == read.back + Plan.cross and read.struck - time.strike.arm > read.back 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); }