//! The state column (design/README.md, "3. Panels"): `registers`, all //! seventeen, each followed as far as it points; `stack`, the words from //! rsp with the frames they belong to as `call` spans down its right edge //! and the registers that point at a word as `pin`s in its lane; and //! `backtrace`, the call chain as rows, a panel of its own only in the //! `none` split. Ink says what a thing is, paper what happened to it. //! Reads `Moment.regs`, `Moment.read`, the mappings (through //! `zt.telescope`), and the names the debugger recorded. 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 syscalls = @import("syscalls.zig"); const ties = @import("ties.zig"); const Stage = @import("stage.zig").Stage; const theme = ui.theme; const time = theme.time; const Rect = ui.Rect; const t = theme.color.text; const m = theme.metric.context; pub const ink = rows.ink; pub const regionOf = rows.regionOf; /// The registers' tag: the legend of what an address's ink says, always on screen, as pwndbg's is. pub const legend = blk: { const c = theme.color.region; break :blk [_]ui.Legend{ .{ .text = "stack", .ink = ui.rgb(c.stack) }, .{ .text = "heap", .ink = ui.rgb(c.heap) }, .{ .text = "code", .ink = ui.rgb(c.code_) }, .{ .text = "data", .ink = ui.rgb(c.data) }, .{ .text = "rwx", .ink = ui.rgb(c.data), .under = true }, .{ .text = "read-only", .ink = ui.rgb(c.rodata) }, }; }; /// A panel's `Ui`, moved to where the stage has its box now. pub fn at(f: *sk.Frame, placed: anim.Placed, box: Rect) ui.Ui { return (ui.Ui{ .f = f, .at = placed }).moved(box.x, box.y); } pub fn veiled(u: ui.Ui, box: Rect, amount: f32) void { // Staging: what cannot be read at a sprint is dimmed, not removed. u.veil(.{ .x = theme.stroke.rule, .y = m.tag, .w = box.w - 2 * theme.stroke.rule, .h = box.h - m.tag - theme.stroke.rule }, amount); } /// The rows a panel `box` shows: while a relayout moves it, one more, cut by its edge. pub fn rowsOf(box: Rect) usize { return @intFromFloat(@max(@ceil((box.h - m.tag - 2 * m.pad) / m.row), 0)); } pub fn clipBody(u: ui.Ui, box: Rect) void { u.clip(.{ .x = theme.stroke.rule, .y = m.tag + m.pad - 1, .w = box.w - 2 * theme.stroke.rule, .h = box.h - m.tag - 2 * m.pad + 2 }); } pub const Registers = struct { cursor: cursors.Cursor, stage: *const Stage, /// A step that makes a system call frames, as read, the registers /// that carry it, one at a time; and rax is struck when it returns. syscalls: bool = false, /// No strikes: for a program whose instrumentation uses the registers /// between any two lines, so that nearly all of them change at every one. quiet: bool = false, focus: bool = false, const Shown = struct { regs: zt.Regs, moment: Recording.Moment }; pub fn draw(r: *const Registers, f: *sk.Frame, placed: anim.Placed) void { const box = r.stage.box(placed, .registers); const u = at(f, placed, box); const now = r.cursor.now(placed); const rec = r.cursor.rec; const is: Shown = .{ .regs = (now.moment().regs(rec.tid) catch null) orelse zt.Regs{}, .moment = now.moment() }; const was: Shown = .{ .regs = (now.before().regs(rec.tid) catch null) orelse is.regs, .moment = now.before() }; const body = u.panel(box.w, box.h, "registers", .{ .focus = r.focus, .legend = &legend }); // A link leaves from the panel's edge, not through a name. ties.anchor(u, .registers, .{ .x = 0, .y = 0, .w = box.w, .h = box.h }); clipBody(u, box); defer u.unclip(); const shown = @min(rowsOf(box), theme.metric.all_registers.len); // Overlapping action: of the registers one step wrote, each strikes 2 f after the one above it. for (theme.metric.all_registers[0..shown], 0..) |name, i| { const y = body.y + m.pad + @as(f32, @floatFromInt(i)) * m.row; if (std.mem.eql(u8, name, "rip")) { r.rip(u, now, y, box.w, is, was); continue; } r.row(u, now, is, was, name, y, box.w); } veiled(u, box, now.veil); } fn shownAt(rec: *const Recording, i: u64) ?Shown { const moment = rec.moment(i); return .{ .regs = (moment.regs(rec.tid) catch return null) orelse return null, .moment = moment }; } /// rip: where execution is, a current mark like the source's and the /// disassembly's; it moves with them, at the advance. fn rip(r: *const Registers, u: ui.Ui, now: cursors.Now, y: f32, w: f32, is: Shown, was: Shown) void { const rec = r.cursor.rec; const moment = now.marks[if (now.advancing() >= 0.5) 1 else 0]; // The flags' ticks are secondary: 6 f after the registers strike, not with them. const landed = now.landed(.cpu, cursors.write_apart); const flags = (if (landed) is else was).regs.eflags; // The flags a step changed are ticked, for three steps. const eflags_index = comptime index("eflags").?; // Until this step's change lands, the ticks are the last one's: no effect before its cause. const age = if (landed) now.registerAge(eflags_index) else now.registerAgeFrom(eflags_index, 1); var changed: u64 = 0; if (age) |a| changed = rec.register(now.stops[a], "eflags") ^ rec.register(now.stops[a + 1], "eflags"); const held = if (r.quiet) 0 else now.register(eflags_index, cursors.write_apart).level; rows.rip(u, y, w, rec.moment(moment), rec.register(moment, "rip"), flags, changed, held, 0); } fn row(r: *const Registers, u: ui.Ui, now: cursors.Now, line_is: Shown, line_was: Shown, name: []const u8, y: f32, w: f32) void { const rec = r.cursor.rec; const i = index(name) orelse return; // Every register is the program's, at its line stops, as every // other panel is: what crossed into the kernel is the crossing's // to show, and a register is framed as carrying it only where it // still holds what crossed. const is = line_is; const was = line_was; const value_now = is.regs.named(name) orelse return; const value_was = was.regs.named(name) orelse value_now; var marks: rows.Marks = .{}; var landed = now.landed(.cpu, 0); var note: []const u8 = ""; const crossing: ?Recording.Syscall = if (r.syscalls) syscalls.inStep(now) else null; // A register the call neither carries nor answers in is any register. const takes_part = if (crossing) |made| std.mem.eql(u8, name, "rax") or for (syscalls.carried(made), 0..) |carried, k| { if (std.mem.eql(u8, carried, name) and value_now == made.args[k]) break true; } else false else false; if (if (takes_part) crossing else null) |made| { const plan = syscalls.Plan.of(made); const is_rax = std.mem.eql(u8, name, "rax"); const carrier: ?usize = if (is_rax) null else for (syscalls.carried(made), 1..) |carried, k| { if (std.mem.eql(u8, carried, name) and value_now == made.args[k - 1]) break k; } else null; // What carries the call is framed as read, one register at a // time: they are what crosses the line. const framed = now.time - plan.registers - @as(f32, @floatFromInt(carrier orelse 0)) * time.flight.second; landed = framed >= 0; if (carrier != null) { marks.read = 0; marks.read_shows = @min(std.math.clamp(framed / time.read.in, 0, 1), now.reading(.cpu, 0)); // A descriptor says what it is open on: the `value` class `fd`. const names = zt.syscalls.names(made.nr); if (landed and carrier.? >= 1 and carrier.? <= names.len and std.mem.endsWith(u8, names[carrier.? - 1], "fd")) note = rec.openOn(u.f.scratch, value_now, made.enter); } if (is_rax) { // rax: what was there, then the result coming back (the // call's number is the crossing's: it went in at the wrapper). const back = now.time - plan.returns; const result = back >= time.strike.in / 2.0; const value: u64 = if (result) value_now else value_was; if (back >= -time.strike.arm) { marks = .{ .first = now.heat(0, null, back) }; if (back >= 0 and now.walking()) marks.extend = back; } const hops = rows.reg(u, y, w, name, if (result) is.moment else was.moment, value, marks); // What `open` gave back is a descriptor: the `value` class // `fd`, this call's once it is back, the last one's before. const gave = if (result) made else if (syscalls.latest(rec, now.stops[1])) |n| rec.syscalls[n] else null; if (gave) |g| if (g.exit != null and g.result == value and std.mem.eql(u8, zt.syscalls.name(g.nr) orelse "", "open")) fdNote(u, hops, y, rec.openOn(u.f.scratch, value, g.exit.? + 1)); return anchor(u, i, hops, y); } } else if (r.quiet) { // Unmarked: the values change as the mark moves on. landed = now.advancing() >= 0.5; } else { const age = now.registerAge(i); // In a step that crosses into the kernel, what else the line // changed is seen after the call is back. const after_call: f32 = if (crossing) |made| syscalls.Plan.of(made).returns - syscalls.Plan.of(made).registers else 0; const delay = (if (age == 0) ties.strikeDelay(now, i) else 0) + after_call; landed = now.landed(.cpu, delay); marks.first = now.register(i, delay); // A register written: the rest of its chain is followed again. const since = now.since(.cpu, delay); if (age == 0 and now.walking() and since >= 0) marks.extend = since; } const hops = rows.reg(u, y, w, name, if (landed) is.moment else was.moment, if (landed) value_now else value_was, marks); fdNote(u, hops, y, note); anchor(u, i, hops, y); } /// The `fd` class's note after a register's value: faint, what it is open on. fn fdNote(u: ui.Ui, hops: rows.Hops, y: f32, on: []const u8) void { if (hops.n > 0 and on.len > 0) u.text(.mono, theme.size.mono.context, hops.end + 8, rows.baseline(y), on, t.faint); } fn anchor(u: ui.Ui, i: usize, hops: rows.Hops, y: f32) void { if (hops.n > 0) ties.anchor(u, .{ .register = i }, .{ .x = hops.x[0], .y = y, .w = hops.w[0], .h = m.row }); } }; /// A register's place in `Regs.names`. pub fn index(name: []const u8) ?usize { for (zt.Regs.names, 0..) |known, i| if (std.mem.eql(u8, known, name)) return i; return null; } /// One frame of the call chain, on the stack: its function's pc, and the /// slots that are the frame, from `lo` to `hi` (the last; null: its end is /// not known, past what the recording holds). pub const Frame = struct { pc: u64, lo: u64, hi: ?u64 }; /// The frames at moment `i`, newest first, with their extents, as the /// tracer reads them off the frame-pointer chain. pub fn frames(rec: *const Recording, i: u64, out: []Frame) []Frame { const moment = rec.moment(i); const regs = (moment.regs(rec.tid) catch return out[0..0]) orelse return out[0..0]; var buf: [24]zt.Debugger.Frame = undefined; const found = zt.telescope.frames(moment, ®s, buf[0..@min(buf.len, out.len)]) catch return out[0..0]; for (found, out[0..found.len]) |f, *o| o.* = .{ .pc = f.pc, .lo = f.low, .hi = if (f.high > f.low) f.high - 8 else null }; return out[0..found.len]; } /// A frame's span on the stack: its function's name, and as a call its /// argument where it takes one (`fib(4)`): the digits on its node. fn spanName(u: ui.Ui, rec: *const Recording, open: []const Recording.Call, i: usize, pc: u64) []const u8 { const name = frameName(u, rec, pc); if (i >= open.len) return name; const call = open[open.len - 1 - i]; if (!std.mem.eql(u8, rec.name(call.function), name)) return name; const takes = for (rec.functions) |f| { if (std.mem.eql(u8, f.name, name)) break f.takes; } else false; const arg = call.arg orelse return name; if (!takes) return name; const v = ui.Value.of(arg, rows.regionOf(rec.moment(call.enter), arg) != .none); // A small number in decimal, as on the node; anything else as its class has it. return if (v.decimal) u.print("{s}({d})", .{ name, arg }) else u.print("{s}({s}{s})", .{ name, v.prefix, v.digits() }); } /// A frame's name: its function's (no offset), or its module's and offset where there is no symbol. pub fn frameName(u: ui.Ui, rec: *const Recording, pc: u64) []const u8 { const name = rec.strings.get(pc) orelse return u.print("{x}", .{pc}); if (std.mem.indexOfScalar(u8, name, '!') != null) return ui.symbol(u, name); return name[0 .. std.mem.lastIndexOfScalar(u8, name, '+') orelse name.len]; } /// The registers (of the sixteen) that hold `addr` in `regs`. fn pointing(u: ui.Ui, regs: zt.Regs, addr: u64) []const []const u8 { var out: std.ArrayList([]const u8) = .empty; for (theme.metric.all_registers[0..16]) |name| { if (regs.named(name) == addr) out.append(u.f.scratch, name) catch break; } return out.items; } pub const Stack = struct { cursor: cursors.Cursor, stage: *const Stage, focus: bool = false, pub fn draw(k: *const Stack, f: *sk.Frame, placed: anim.Placed) void { const box = k.stage.box(placed, .stack); const u = at(f, placed, box); const now = k.cursor.now(placed); const rec = k.cursor.rec; const slots = rowsOf(box); const is = (now.moment().regs(rec.tid) catch null) orelse return; const was = (now.before().regs(rec.tid) catch null) orelse is; // The window: from rsp, or further into the frame ([rsp, rbp+16)) // when that is longer than the panel, so that the word the last // steps touched is in its middle. When a step moves it the rows // slide, with the stack's words, a level after the registers. // Under the camera the window holds still, `free` words above the // rsp it was held at: pushes fill them, and rsp's pin climbs. const hold = placed.value(k.stage.hold); const held = hold >= 0; const held_at: u64 = if (held) rec.register(@intFromFloat(hold), "rsp") -% 8 * @as(u64, @intFromFloat(placed.value(k.stage.hold_free))) else 0; const window = if (held) [2]u64{ held_at, held_at } else [2]u64{ windowAt(now, is, slots, 0), windowAt(now, was, slots, 1) }; // Going to the hold and coming from it, the rows scroll: the // remaining way, in rows, from where the window would be. const natural = windowAt(now, is, slots, 0); const hold_scroll: f32 = if (held) @as(f32, @floatFromInt(@as(i64, @bitCast(held_at -% natural)))) / 8 * (1 - cursors.glide(placed.value(k.stage.hold_in))) else 0; const landed = now.landed(.memory, 0); // From rsp, or the range shown when the window is elsewhere: in // bytes from rsp, as the catalogue writes it (`rsp+20 to rsp+48`). const from_rsp: i64 = if (landed) @bitCast(window[0] -% is.rsp) else @bitCast(window[1] -% was.rsp); const offset = struct { fn of(u_: ui.Ui, d: i64) []const u8 { return if (d == 0) "rsp" else if (d > 0) u_.print("rsp+{x}", .{@as(u64, @intCast(d))}) else u_.print("rsp-{x}", .{@as(u64, @intCast(-d))}); } }.of; const words = switch (slots) { 4 => "four", 6 => "six", 8 => "eight", else => u.print("{d}", .{slots}), }; const range = if (from_rsp == 0) u.print("{s} words from rsp", .{words}) else u.print("{s} to {s}", .{ offset(u, from_rsp), offset(u, from_rsp + 8 * @as(i64, @intCast(slots))) }); const body = u.panel(box.w, box.h, "stack", .{ .focus = k.focus, .note = u.print("{s} \u{00b7} the frames they belong to", .{range}) }); const p = cursors.glide(now.moving(.memory, 0, time.move)); const moved = @as(f32, @floatFromInt(@as(i64, @bitCast(window[0] -% window[1])))) / 8; const slide: f32 = (if (@abs(moved) > 16) 0 else moved * (1 - p)) + hold_scroll; const top = body.y + m.pad; clipBody(u, box); defer u.unclip(); // The addresses' shared digits: the rows read by their ends, of the // window shown (it changes with the slide, not before it). const shown_at = if (landed) window[0] else window[1]; const lead = ui.shared(&.{ shown_at, shown_at + 8 * @as(u64, slots) }); const memory = now.shown(.memory); // rsp and rbp, moved by the step with no link to land: their tags // travel down the lane from the old word to the new, with the slide. var travel_buf: [2][]const u8 = undefined; var travelling: usize = 0; for ([_][]const u8{ "rsp", "rbp" }) |name| if (!now.resting() and was.named(name) != is.named(name)) { travel_buf[travelling] = name; travelling += 1; }; const travel = travel_buf[0..travelling]; var n: i64 = @as(i64, @intFromFloat(@floor(-slide))) - 1; while (n <= @as(i64, @intCast(slots)) - @as(i64, @intFromFloat(@floor(slide)))) : (n += 1) { const y = top + (@as(f32, @floatFromInt(n)) + slide) * m.row; if (y + m.row < body.y or y > box.h) continue; const addr = window[0] +% @as(u64, @bitCast(n * 8)); // Who points here: a pin in the lane, landing with its link. const names = pins(u, now, is, was, addr, travel); var marks: rows.Marks = .{ .lead = lead, .first = now.written(addr, 8, .memory, 0) }; if (now.wasRead(addr, 8) and now.writeAge(addr, 8) != 0) { marks.read = 0; marks.read_shows = now.reading(.memory, 0); } // `free`: above rsp, not yet reached: its address at 60%, its word faint. if (held and addr < (if (landed) is.rsp else was.rsp)) { rows.free(u, y, memory, addr, lead); continue; } const hops = rows.slot(u, y, box.w, memory, addr, names.names, names.shows, marks); // Only a row on show is a place a tie can land. if (y >= top - 1 and y + m.row <= box.h - m.pad + 1) { ties.anchor(u, .{ .word = addr }, .{ .x = theme.metric.slot.chain, .y = y, .w = if (hops.n > 0) hops.x[0] + hops.w[0] - theme.metric.slot.chain else 120, .h = m.row }); ties.anchor(u, .{ .slot_pin = addr }, .{ .x = theme.metric.slot.lane, .y = y, .w = theme.metric.slot.lane_end - theme.metric.slot.lane, .h = m.row }); } } // Where the window is, for a link to a word outside it. const lane_at = u.at.xf.apply(.{ theme.metric.slot.lane, top }); const row_px = u.at.xf.apply(.{ 0, top + m.row })[1] - lane_at[1]; ties.stack_window = .{ .first = window[0], .slots = slots, .x = lane_at[0], .top = lane_at[1], .row = row_px }; // The travelling tags: both of them at one word share a pin. const going = cursors.standard(if (now.resting()) 1 else std.math.clamp(now.since(.cpu, 0) / time.move, 0, 1)); var places: [2]f32 = undefined; for (travel, places[0..travel.len]) |name, *place| { const at_old = @as(f32, @floatFromInt(@as(i64, @bitCast((was.named(name) orelse 0) -% window[0])))) / 8 + slide; const at_new = @as(f32, @floatFromInt(@as(i64, @bitCast((is.named(name) orelse 0) -% window[0])))) / 8 + slide; place.* = std.math.lerp(at_old, at_new, going); } for (travel, places[0..travel.len], 0..) |name, place, i| { if (i == 1 and @abs(places[0] - place) < 0.05) continue; if (place < -0.5 or place > @as(f32, @floatFromInt(slots)) - 0.5) continue; const both = i == 0 and travel.len == 2 and @abs(places[1] - place) < 0.05; u.pinRow(theme.metric.slot.lane, top + place * m.row, if (both) &.{ "rsp", "rbp" } else &.{name}, theme.color.region.stack); } // The backtrace, drawn on the words that are each frame: each span // glides from the frame's old extent to its new one with the slide. var buf: [16]Frame = undefined; var old_buf: [16]Frame = undefined; const chain = frames(rec, now.stops[0], &buf); const old_chain = frames(rec, now.stops[1], &old_buf); // Placed as the rows are: against the window after the step, and slid. const open_calls = rec.stack(u.f.scratch, if (landed) now.stops[0] else now.stops[1]); const named = if (landed) chain else old_chain; const rows_of = struct { fn at(addr: u64, base: u64) f32 { return @as(f32, @floatFromInt(@as(i64, @bitCast(addr -% base)))) / 8; } }.at; for (chain, 0..) |frame, i| { const old_frame = if (i < old_chain.len) old_chain[i] else frame; const first = std.math.lerp(rows_of(old_frame.lo, window[0]), rows_of(frame.lo, window[0]), p) + slide; if (first >= @as(f32, @floatFromInt(slots))) break; const last = if (frame.hi) |hi| std.math.lerp(if (old_frame.hi) |oh| rows_of(oh, window[0]) else rows_of(hi, window[0]), rows_of(hi, window[0]), p) + slide else std.math.inf(f32); if (last < 0) continue; const open = last >= @as(f32, @floatFromInt(slots)); const y1 = top + (@min(last, @as(f32, @floatFromInt(slots)) - 1) + 1) * m.row; rows.span(u, box.w, top + @max(first, 0) * m.row, y1, spanName(u, rec, open_calls, i, if (i < named.len) named[i].pc else frame.pc), i == 0, open); } veiled(u, box, now.veil); } /// The first word a window of `slots` shows, `skip` steps back: rsp, /// or within [rsp, rbp+16) (the frame, with its saved rbp and its way /// back) so that the word the newest of the last three steps wrote or /// read there is in the window's middle. fn windowAt(now: cursors.Now, regs: zt.Regs, slots: usize, skip: usize) u64 { const frame_end = regs.rbp +% 16; if (frame_end <= regs.rsp or frame_end - regs.rsp > 8 * 64) return regs.rsp; const words = (frame_end - regs.rsp) / 8; if (words <= slots) return regs.rsp; for (skip..skip + 3) |age| { if (age + 1 >= now.stops.len) break; for ([_][]const Recording.Span{ now.rec.written(now.stops[age + 1], now.stops[age]), now.rec.read(now.stops[age + 1], now.stops[age]) }) |spans| { var k = spans.len; while (k > 0) { k -= 1; const a = spans[k].addr; if (a < regs.rsp or a >= frame_end) continue; const word = (a - regs.rsp) / 8; const first = @min(word -| (slots - 1) / 2, words - slots); return regs.rsp + 8 * first; } } } return regs.rsp; } const Pins = struct { names: []const []const u8, shows: f32 }; /// The registers whose value is `addr`: before the step, and after it /// once their link has landed (`ties.pinShows`). fn pins(u: ui.Ui, now: cursors.Now, is: zt.Regs, was: zt.Regs, addr: u64, apart: []const []const u8) Pins { var out: std.ArrayList([]const u8) = .empty; var shows: f32 = 0; for (theme.metric.all_registers[0..16]) |name| { // Those drawn apart, travelling. if (for (apart) |a| { if (std.mem.eql(u8, a, name)) break true; } else false) continue; const i = index(name).?; const before = was.named(name) == addr; const after = is.named(name) == addr; if (!before and !after) continue; const s = ties.pinShows(now, i, .slot); const this = if (before and after) 1 else if (after) s.new else s.old; if (this < 0.5) continue; out.append(u.f.scratch, name) catch break; shows = @max(shows, this); } return .{ .names = out.items, .shows = shows }; } }; pub const Backtrace = struct { cursor: cursors.Cursor, stage: *const Stage, focus: bool = false, pub fn draw(b: *const Backtrace, f: *sk.Frame, placed: anim.Placed) void { const box = b.stage.box(placed, .backtrace); if (box.h < m.tag) return; const u = at(f, placed, box); const now = b.cursor.now(placed); const rec = b.cursor.rec; var buf: [24]Frame = undefined; const chain = frames(rec, now.stop(.cpu), &buf); const room = rowsOf(box); const body = u.panel(box.w, box.h, "backtrace", .{ .focus = b.focus, .note = if (chain.len > room) u.print("newest on top \u{00b7} {d} more", .{chain.len - room}) else "newest on top" }); clipBody(u, box); defer u.unclip(); for (chain[0..@min(chain.len, room)], 0..) |frame, i| { const y = body.y + m.pad + @as(f32, @floatFromInt(i)) * m.row; const name = ui.symbol(u, rec.strings.get(frame.pc) orelse u.print("{x}", .{frame.pc})); // The program's own frame says where in its source it is. const where = if (i == 0) u.print("{s}:{d}", .{ rec.file, rec.own[now.marked()] }) else if (rec.lineOf(frame.pc)) |l| u.print("{s}:{d}", .{ rec.file, l }) else ""; const open = rec.stack(u.f.scratch, now.stop(.cpu)); const args = if (i < open.len) @import("calls.zig").arguments(u, rec, open[open.len - 1 - i]) else ""; rows.callRow(u, y, box.w, i, name, args, where, i == 0); } veiled(u, box, now.veil); } }; test "the flags' bits" { try std.testing.expectEqual(@as(?usize, 17), index("eflags")); }