//! USDT, the static probes of DTrace and SystemTap: a program built with //! 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, } }; if (std.mem.indexOfScalar(u8, &.{ 1, 2, 4, 8 }, arg.at.memory.scale) == null) return error.BadUsdtArg; } 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(®s, memory)); for ([_][]const u8{ "4@counter(%rip)", "3@%eax", "4@%ah", "4", "4@", "4@8(%rdx", "4@%r8x", "4@(%rdx,%rax,3)" }) |bad| { try std.testing.expectError(error.BadUsdtArg, Arg.parse(bad)); } }