//! The one record every backend produces (ptrace, the in-process agent, //! LLVM instrumentation, kernel tracing) and every consumer reads (the //! recorder, the animations). 64 bytes, plus an optional payload carried //! beside it. `extern` because it crosses processes (the ring) and is //! written to disk (the recorder). const std = @import("std"); pub const Kind = enum(u16) { // Execution stops. Payload: `Regs`, when the backend has them. /// a0=pc step = 1, /// a0=pc a1=breakpoint id breakpoint = 2, /// aux=nr a0..a5=args. Payload: optional decoded bytes (a path). syscall_enter = 3, /// aux=nr a0=return value syscall_exit = 4, /// aux=signo a0=fault address a1=pc signal = 5, /// a0=exit code, or 128+signo when killed exit = 6, /// a0=new tid thread_start = 7, thread_exit = 8, // Memory. /// a0=addr a1=len. Payload: the bytes now at addr (len of them, or the /// first of them: a backend may record a large write in part). mem_write = 16, /// a0=addr a1=len a2=pc (0: not given) mem_read = 17, /// a0=ptr a1=size a2=caller pc. aux: `Alloc`. A realloc that moves is a /// `free` of the old pointer, then this. alloc = 18, /// a0=ptr a1=caller pc free = 19, /// a0=addr a1=len a2=prot a3=file offset. Payload: path, if file-backed. map = 20, /// a0=addr a1=len unmap = 21, /// The instruction at the pc is about to touch memory: a0=addr a1=len /// a2=pc. aux: 1 it reads there, 2 it writes there, 3 both. From a /// debugger, which sees the instruction before it runs; what is there is /// recorded beside it, and what a write left there after the step. What /// its operands name, then what the stack's own instructions touch /// without naming it (`Debugger.Touch`). touch = 22, /// The instruction at the pc is a call, a jump or a return: a0=where it /// goes a1=1 when it will go there (0: a conditional jump that falls /// through) a2=pc. aux: 1 call, 2 jump, 3 return. From a debugger, /// before the instruction runs; the target is named like any code address. branch = 23, // Instrumentation (compiler passes, hooks). /// a0=callee (the string id of its name, or its address when the /// backend has no names) a1=call site a2=sp a3=string id of the /// function's type description, if any call = 32, /// a0=callee a1=return value. aux: how many bytes of a1 are the value /// (0: none, or not known) ret = 33, /// a0=file string id (0 clears the location) a1=line a2=column a3=pc (0: not given) line = 34, /// a0=pc (a coverage edge) edge = 35, /// aux=operand bytes a0=pc a1=lhs a2=rhs cmp = 36, /// A named variable comes alive: a0=addr a1=size a2=name string id /// a3=type string id (a description: src/instr/types.zig). aux: N for a /// function's Nth parameter. variable = 37, // Kernel. /// a0=prev tid a1=next tid a2=cpu sched = 48, /// a0=fault address a1=pc. aux: fault flags. fault = 49, /// a0=pc a1=counter id a2=value sample = 50, /// A kprobe, uprobe, tracepoint or USDT probe: a0=probe string id a1..a5=arguments probe = 51, // Annotations. /// a0=user value. Payload: text. mark = 60, /// Defines a string id for later events: a0=id. Payload: the text. string = 61, _, /// The bit of a kind in a 64-bit set (kinds are all below 64). pub fn bit(k: Kind) u64 { return @as(u64, 1) << @intCast(@intFromEnum(k)); } }; pub const Alloc = enum(u16) { malloc, calloc, realloc, memalign, mmap }; pub const Event = extern struct { /// CLOCK_MONOTONIC nanoseconds. ts: u64 = 0, /// 0 for an event no thread made (a string defined at startup). tid: u32 = 0, kind: Kind, /// Small kind-specific value (syscall number, signal, operand size). aux: u16 = 0, a: [6]u64 = @splat(0), comptime { std.debug.assert(@sizeOf(Event) == 64); } }; /// Where events go. A recorder, a ring, a printer. pub const Sink = struct { ctx: *anyopaque, emitFn: *const fn (ctx: *anyopaque, ev: *const Event, payload: []const u8) anyerror!void, pub fn emit(s: Sink, ev: Event, payload: []const u8) !void { return s.emitFn(s.ctx, &ev, payload); } }; /// x86-64 general registers, in the kernel's `user_regs_struct` order, so /// PTRACE_GETREGS fills it directly. pub const Regs = extern struct { r15: u64 = 0, r14: u64 = 0, r13: u64 = 0, r12: u64 = 0, rbp: u64 = 0, rbx: u64 = 0, r11: u64 = 0, r10: u64 = 0, r9: u64 = 0, r8: u64 = 0, rax: u64 = 0, rcx: u64 = 0, rdx: u64 = 0, rsi: u64 = 0, rdi: u64 = 0, orig_rax: u64 = 0, rip: u64 = 0, cs: u64 = 0, eflags: u64 = 0, rsp: u64 = 0, ss: u64 = 0, fs_base: u64 = 0, gs_base: u64 = 0, ds: u64 = 0, es: u64 = 0, fs: u64 = 0, gs: u64 = 0, comptime { std.debug.assert(@sizeOf(Regs) == 27 * 8); } /// The registers a viewer shows, in display order. pub const names = [_][]const u8{ "rax", "rbx", "rcx", "rdx", "rsi", "rdi", "rbp", "rsp", "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15", "rip", "eflags" }; pub fn get(r: *const Regs, comptime name: []const u8) u64 { return @field(r, name); } /// By name at runtime: null for a name that is no register. pub fn named(r: *const Regs, name: []const u8) ?u64 { inline for (@typeInfo(Regs).@"struct".field_names) |f| { if (std.mem.eql(u8, f, name)) return @field(r, f); } return null; } }; /// The id of a string, for a producer that keeps no table: its text's /// hash, with the top bit set. The instrumentation counts its strings from /// 1, and a symbol's name is the string whose id is its address; a hash up /// here meets neither, so the producers of one recording (a debugger, an /// agent and instrumentation at once) never define an id twice. pub fn stringId(text: []const u8) u64 { return std.hash.Wyhash.hash(0, text) | 1 << 63; } /// The id of the string that describes the instruction at `addr`: a byte /// for its length, a byte for the length of the instruction before it (0 /// when that is not known), then its text ("mov rbp, rsp"). The string whose id is /// `addr` itself is the address's name ("main+4"). Addresses stay below /// bit 47 and hashed ids have bit 63: bit 62 keeps the two apart. pub fn codeId(addr: u64) u64 { return addr | 1 << 62; } /// The id of the string that describes the frame of the function that /// begins at `addr`: how to walk through it to its caller (its call frame /// information) and where its locals are (`Debugger.emitFunction`). A /// reader finds the one that holds a pc as the greatest id at or below the /// pc's (`Trace.stringBelow`). `frameId(0)`, where no function begins, is /// the process's first stack (`Debugger.Start`). Bit 61 keeps these apart /// from names, instructions and hashed ids. pub fn frameId(addr: u64) u64 { return addr | 1 << 61; } /// The id of the string that tells of the file mapped at `path`: its build /// id and where its debug info came from (`Debugger.emitModule`). pub fn moduleId(path: []const u8) u64 { return std.hash.Wyhash.hash(1, path) | 1 << 63; } /// The id of the string that holds the basic blocks of the function that /// begins at `addr` (`Debugger.emitBlocks`), found as a frame's is: the /// greatest at or below the pc's. Bits 61 and 62 both. pub fn blocksId(addr: u64) u64 { return addr | 3 << 61; } pub fn now() u64 { var ts: std.os.linux.timespec = undefined; _ = std.os.linux.clock_gettime(.MONOTONIC, &ts); return @as(u64, @intCast(ts.sec)) * std.time.ns_per_s + @as(u64, @intCast(ts.nsec)); } test "kind bits fit a u64 set" { inline for (@typeInfo(Kind).@"enum".field_values) |v| try std.testing.expect(v < 64); try std.testing.expectEqual(@as(?u64, 7), (Regs{ .rip = 7 }).named("rip")); }