summaryrefslogtreecommitdiff
path: root/src/trace/usdt.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:39:20 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:19:06 -0300
commitdb923fa823354270217362db06356f2b1a41315e (patch)
tree676ad2dbfd59f0677200d85616ef1ed14d058981 /src/trace/usdt.zig
parenta7504c6bb2ec9e906891e42bc3df28b276e67143 (diff)
downloadcomputeranim-db923fa823354270217362db06356f2b1a41315e.tar.gz
computeranim-db923fa823354270217362db06356f2b1a41315e.zip
ztrace perf: the kernel's view of a program, unprivileged
perf_event_open on a held child: counters, a sampling profile, every page fault with its registers, maps, threads, context switches, every syscall (the per-syscall tracepoints, the only ones open to a user), and the debug registers as watchpoints and breakpoints that do not stop the target. One time-ordered stream of Events into a Sink; --threads follows with a ring per CPU. usdt.zig: the notes of <sys/sdt.h> and their arguments from a Regs and a memory reader, independent of BPF. test-kernel runs all of it on targets/kernel_*. Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'src/trace/usdt.zig')
-rw-r--r--src/trace/usdt.zig284
1 files changed, 284 insertions, 0 deletions
diff --git a/src/trace/usdt.zig b/src/trace/usdt.zig
new file mode 100644
index 0000000..ba03079
--- /dev/null
+++ b/src/trace/usdt.zig
@@ -0,0 +1,284 @@
+//! USDT, the static probes of DTrace and SystemTap: a program built with
+//! <sys/sdt.h> has a nop where each probe is and an ELF note saying where
+//! that is and where the probe's arguments live then. This reads the notes
+//! and fetches the arguments from a stopped thread's registers and memory.
+//! Getting stopped there is the caller's business: a breakpoint under
+//! ptrace, a uprobe with BPF. Also the little of ELF both need: sections,
+//! symbols, where a file's addresses land in a process. x86-64.
+const std = @import("std");
+const linux = std.os.linux;
+const Regs = @import("event.zig").Regs;
+const E = std.elf.Elf64;
+
+/// A 64-bit little-endian ELF file in memory.
+pub const Elf = struct {
+ bytes: []align(4096) const u8,
+
+ /// Maps the file at `path`.
+ pub fn open(path: [*:0]const u8) !Elf {
+ const fd = linux.open(path, .{}, 0);
+ if (linux.errno(fd) != .SUCCESS) return error.FileNotFound;
+ defer _ = linux.close(@intCast(fd));
+ const size = linux.lseek(@intCast(fd), 0, linux.SEEK.END);
+ if (linux.errno(size) != .SUCCESS or size < @sizeOf(E.Ehdr)) return error.NotElf;
+ const base = linux.mmap(null, size, .{ .READ = true }, .{ .TYPE = .PRIVATE }, @intCast(fd), 0);
+ if (linux.errno(base) != .SUCCESS) return error.NotElf;
+ const e: Elf = .{ .bytes = @as([*]align(4096) const u8, @ptrFromInt(base))[0..size] };
+ const ident = e.header().ident;
+ if (!std.mem.eql(u8, &ident.magic, std.elf.MAGIC) or ident.class != .@"64" or ident.data != .@"2LSB") {
+ e.close();
+ return error.NotElf;
+ }
+ return e;
+ }
+
+ pub fn close(e: Elf) void {
+ _ = linux.munmap(e.bytes.ptr, e.bytes.len);
+ }
+
+ fn header(e: Elf) *const E.Ehdr {
+ return @ptrCast(e.bytes.ptr);
+ }
+
+ fn table(e: Elf, comptime T: type, at: u64, count: u64) []align(1) const T {
+ if (at > e.bytes.len or count > (e.bytes.len - at) / @sizeOf(T)) return &.{};
+ return @as([*]align(1) const T, @ptrCast(e.bytes.ptr + at))[0..count];
+ }
+
+ fn contents(e: Elf, s: E.Shdr) []const u8 {
+ return if (s.type == .NOBITS) "" else e.table(u8, s.offset, s.size);
+ }
+
+ pub fn section(e: Elf, name: []const u8) ?E.Shdr {
+ const h = e.header();
+ const all = e.table(E.Shdr, h.shoff, h.shnum);
+ if (h.shstrndx >= all.len) return null;
+ const names = e.contents(all[h.shstrndx]);
+ for (all) |s| {
+ if (s.name < names.len and std.mem.eql(u8, std.mem.sliceTo(names[s.name..], 0), name)) return s;
+ }
+ return null;
+ }
+
+ /// A symbol by name, from the full table when the file still has one,
+ /// else from the dynamic one.
+ pub fn symbol(e: Elf, name: []const u8) ?E.Sym {
+ for ([_][]const u8{ ".symtab", ".dynsym" }) |table_name| {
+ const s = e.section(table_name) orelse continue;
+ const all = e.table(E.Shdr, e.header().shoff, e.header().shnum);
+ if (s.link >= all.len) continue;
+ const names = e.contents(all[s.link]);
+ for (e.table(E.Sym, s.offset, s.size / @sizeOf(E.Sym))) |sym| {
+ if (sym.shndx == 0 or sym.name >= names.len) continue;
+ if (std.mem.eql(u8, std.mem.sliceTo(names[sym.name..], 0), name)) return sym;
+ }
+ }
+ return null;
+ }
+
+ /// The first loaded segment, or the one that has `containing`.
+ fn load(e: Elf, containing: ?u64) ?E.Phdr {
+ for (e.table(E.Phdr, e.header().phoff, e.header().phnum)) |p| {
+ if (p.type != .LOAD) continue;
+ if (containing) |addr| if (addr < p.vaddr or addr >= p.vaddr + p.memsz) continue;
+ return p;
+ }
+ return null;
+ }
+
+ /// What to add to the file's addresses in a process that has the start
+ /// of the file mapped at `start`: 0 for a fixed-position executable.
+ pub fn bias(e: Elf, start: u64) u64 {
+ const p = e.load(null) orelse return 0;
+ return start -% (p.vaddr - p.offset);
+ }
+
+ /// Where in the file the byte at address `addr` (as the file has it) is:
+ /// what a uprobe is placed by.
+ pub fn offset(e: Elf, addr: u64) ?u64 {
+ const p = e.load(addr) orelse return null;
+ return addr - p.vaddr + p.offset;
+ }
+};
+
+pub const Probe = struct {
+ provider: []const u8,
+ name: []const u8,
+ /// Where the nop is.
+ pc: u64,
+ /// The address of the u16 that a tracer increments to enable the probe,
+ /// for a program that tests it before computing arguments; 0 without.
+ semaphore: u64,
+ /// The arguments as the note has them: "-4@%edi 8@-24(%rbp)".
+ args: []const u8,
+};
+
+/// The probes of `elf`, their addresses moved by `bias` (see `Elf.bias`; 0
+/// gives them as the file and `readelf -n` have them). The strings point
+/// into the file. Free the slice with `gpa`.
+pub fn probes(gpa: std.mem.Allocator, elf: Elf, bias: u64) ![]Probe {
+ var list: std.ArrayList(Probe) = .empty;
+ errdefer list.deinit(gpa);
+ const notes = elf.contents(elf.section(".note.stapsdt") orelse return &.{});
+ // A note records where .stapsdt.base was when it was written: a
+ // prelinker moves the section and not the notes.
+ const base_now = if (elf.section(".stapsdt.base")) |s| s.addr else 0;
+ var at: usize = 0;
+ while (at + 12 <= notes.len) {
+ const name_len = std.mem.readInt(u32, notes[at..][0..4], .little);
+ const desc_len = std.mem.readInt(u32, notes[at + 4 ..][0..4], .little);
+ const kind = std.mem.readInt(u32, notes[at + 8 ..][0..4], .little);
+ const name_at = at + 12;
+ const desc_at = name_at + std.mem.alignForward(usize, name_len, 4);
+ at = desc_at + std.mem.alignForward(usize, desc_len, 4);
+ if (at > notes.len) break;
+ const desc = notes[desc_at..][0..desc_len];
+ if (kind != 3 or desc_len < 24 or !std.mem.eql(u8, notes[name_at..][0..name_len], "stapsdt\x00")) continue;
+ const moved = (if (base_now != 0) base_now -% std.mem.readInt(u64, desc[8..16], .little) else 0) +% bias;
+ const semaphore = std.mem.readInt(u64, desc[16..24], .little);
+ var strings = std.mem.splitScalar(u8, desc[24..], 0);
+ try list.append(gpa, .{
+ .pc = std.mem.readInt(u64, desc[0..8], .little) +% moved,
+ .semaphore = if (semaphore == 0) 0 else semaphore +% moved,
+ .provider = strings.next() orelse "",
+ .name = strings.next() orelse "",
+ .args = strings.next() orelse "",
+ });
+ }
+ return list.toOwnedSlice(gpa);
+}
+
+/// One argument of a probe: its size and where it is at the probe.
+pub const Arg = struct {
+ /// 1, 2, 4 or 8 bytes.
+ size: u8,
+ signed: bool,
+ at: union(enum) {
+ constant: i64,
+ register: Register,
+ /// disp(base, index, scale)
+ memory: struct { base: Register, index: ?Register = null, scale: u8 = 1, disp: i64 = 0 },
+ },
+
+ const Register = struct {
+ /// Which u64 of `Regs`.
+ slot: u8,
+ bytes: u8,
+
+ fn value(r: Register, regs: *const Regs) u64 {
+ const all: *const [@sizeOf(Regs) / 8]u64 = @ptrCast(regs);
+ return if (r.bytes == 8) all[r.slot] else all[r.slot] & (@as(u64, 1) << @intCast(r.bytes * 8)) - 1;
+ }
+ };
+
+ /// "-4@%edi", "8@-24(%rbp)", "4@$7", "8@(%rdx,%rax,8)".
+ /// shortcut: no symbol(%rip) operands and no %ah-style registers, like libbpf; add them when a real probe uses one.
+ pub fn parse(text: []const u8) !Arg {
+ const split = std.mem.indexOfScalar(u8, text, '@') orelse return error.BadUsdtArg;
+ const size = std.fmt.parseInt(i8, text[0..split], 10) catch return error.BadUsdtArg;
+ var arg: Arg = .{ .size = @abs(size), .signed = size < 0, .at = undefined };
+ if (std.mem.indexOfScalar(u8, &.{ 1, 2, 4, 8 }, arg.size) == null) return error.BadUsdtArg;
+ const op = text[split + 1 ..];
+ if (op.len == 0) return error.BadUsdtArg;
+ if (op[0] == '$') {
+ arg.at = .{ .constant = std.fmt.parseInt(i64, op[1..], 0) catch return error.BadUsdtArg };
+ } else if (op[0] == '%') {
+ arg.at = .{ .register = try register(op) };
+ } else {
+ const open = std.mem.indexOfScalar(u8, op, '(') orelse return error.BadUsdtArg;
+ if (op[op.len - 1] != ')') return error.BadUsdtArg;
+ var parts = std.mem.splitScalar(u8, op[open + 1 .. op.len - 1], ',');
+ arg.at = .{ .memory = .{
+ .disp = if (open == 0) 0 else std.fmt.parseInt(i64, op[0..open], 0) catch return error.BadUsdtArg,
+ .base = try register(parts.next().?),
+ .index = if (parts.next()) |r| try register(r) else null,
+ .scale = if (parts.next()) |s| std.fmt.parseInt(u8, s, 10) catch return error.BadUsdtArg else 1,
+ } };
+ }
+ return arg;
+ }
+
+ /// The argument's value, sign- or zero-extended, for a thread stopped
+ /// at the probe with `regs`. `memory` is anything with
+ /// `read(addr: u64, buf: []u8) usize` (a `ptrace.Process`). Null when
+ /// the memory cannot be read.
+ pub fn fetch(arg: Arg, regs: *const Regs, memory: anytype) ?u64 {
+ var bytes: [8]u8 = undefined;
+ switch (arg.at) {
+ .constant => |c| std.mem.writeInt(i64, &bytes, c, .little),
+ .register => |r| std.mem.writeInt(u64, &bytes, r.value(regs), .little),
+ .memory => |m| {
+ const index = if (m.index) |r| r.value(regs) *% m.scale else 0;
+ const addr = m.base.value(regs) +% index +% @as(u64, @bitCast(m.disp));
+ if (memory.read(addr, bytes[0..arg.size]) != arg.size) return null;
+ },
+ }
+ return switch (arg.size) {
+ inline 1, 2, 4, 8 => |n| {
+ const U = @Int(.unsigned, n * 8);
+ const v = std.mem.readInt(U, bytes[0..n], .little);
+ return if (arg.signed) @as(u64, @bitCast(@as(i64, @as(@Int(.signed, n * 8), @bitCast(v))))) else v;
+ },
+ else => unreachable,
+ };
+ }
+};
+
+/// "%rax", "%eax", "%ax", "%al", "%r8d"...
+fn register(text: []const u8) !Arg.Register {
+ if (text.len < 3 or text[0] != '%') return error.BadUsdtArg;
+ const name = text[1..];
+ // The same register at 8, 4, 2 and 1 bytes.
+ const legacy = [_][4][]const u8{
+ .{ "rax", "eax", "ax", "al" }, .{ "rbx", "ebx", "bx", "bl" },
+ .{ "rcx", "ecx", "cx", "cl" }, .{ "rdx", "edx", "dx", "dl" },
+ .{ "rsi", "esi", "si", "sil" }, .{ "rdi", "edi", "di", "dil" },
+ .{ "rbp", "ebp", "bp", "bpl" }, .{ "rsp", "esp", "sp", "spl" },
+ };
+ inline for (legacy) |names| inline for (names, [_]u8{ 8, 4, 2, 1 }) |n, bytes| {
+ if (std.mem.eql(u8, name, n)) return .{ .slot = @offsetOf(Regs, names[0]) / 8, .bytes = bytes };
+ };
+ inline for (8..16) |number| {
+ const full = std.fmt.comptimePrint("r{d}", .{number});
+ if (std.mem.startsWith(u8, name, full)) {
+ const bytes: u8 = if (name.len == full.len) 8 else if (name.len != full.len + 1) 0 else switch (name[full.len]) {
+ 'd' => 4,
+ 'w' => 2,
+ 'b' => 1,
+ else => 0,
+ };
+ if (bytes != 0) return .{ .slot = @offsetOf(Regs, full) / 8, .bytes = bytes };
+ }
+ }
+ return error.BadUsdtArg;
+}
+
+test "argument specs are parsed and fetched" {
+ const regs: Regs = .{ .rdi = 0xffff_ffff_ffff_fffe, .rbp = 0x1000, .rdx = 0x2000, .rax = 3, .r10 = 0x1_0000_00ff };
+ // A memory of its own: every address holds its own low byte, counting up.
+ const memory = struct {
+ fn read(_: @This(), addr: u64, buf: []u8) usize {
+ if (addr >= 0x8000) return 0;
+ for (buf, 0..) |*b, i| b.* = @truncate(addr + i);
+ return buf.len;
+ }
+ }{};
+ const cases = [_]struct { []const u8, ?u64 }{
+ .{ "-4@%edi", @bitCast(@as(i64, -2)) },
+ .{ "4@%edi", 0xffff_fffe },
+ .{ "8@%rdi", 0xffff_ffff_ffff_fffe },
+ .{ "1@%r10b", 0xff },
+ .{ "4@%r10d", 0xff },
+ .{ "-4@$-7", @bitCast(@as(i64, -7)) },
+ .{ "8@$0x10", 16 },
+ .{ "2@-24(%rbp)", 0xe9e8 },
+ .{ "1@(%rdx)", 0 },
+ .{ "4@8(%rdx,%rax,8)", 0x23222120 },
+ .{ "-1@-1(%rbp)", @bitCast(@as(i64, -1)) },
+ .{ "8@0x7000(%rbp)", null },
+ };
+ for (cases) |case| try std.testing.expectEqual(case[1], (try Arg.parse(case[0])).fetch(&regs, memory));
+ for ([_][]const u8{ "4@counter(%rip)", "3@%eax", "4@%ah", "4", "4@", "4@8(%rdx", "4@%r8x" }) |bad| {
+ try std.testing.expectError(error.BadUsdtArg, Arg.parse(bad));
+ }
+}