//! What an address in a target means: the regions mapped into it (from //! /proc/pid/maps), the ELF files behind them with their symbols, and their //! DWARF line tables through `std.debug`. Addresses in and out are the //! target's: a module's load bias is applied here. const Symbols = @This(); const std = @import("std"); const elf = std.elf; const Dwarf = std.debug.Dwarf; gpa: std.mem.Allocator, io: std.Io, maps: Maps = .{}, modules: std.ArrayList(Module) = .empty, /// The line-table row `lineAt` answered from last, as target addresses. row: struct { start: u64 = 0, len: u64 = 0, line: ?Line = null } = .{}, /// A C++ name as its source has it, into `buf`; null for no C++ name. /// Whoever has a demangler sets it (the ztrace command: the C++ runtime's). /// Names are then shown and found so, without their parameters: /// "v8::internal::Heap::CollectGarbage" for "_ZN2v88internal4Heap14Coll...". demangle: ?*const fn (name: []const u8, buf: []u8) ?[]const u8 = null, pub const Mapping = struct { start: u64, end: u64, /// PROT_READ | PROT_WRITE | PROT_EXEC bits. prot: u8, offset: u64, /// The file mapped, or the kernel's name for the region ("[stack]"); empty when anonymous. name: []const u8, }; /// /proc/pid/maps as last read. pub const Maps = struct { /// The file's text: the names in `list` point into it. text: []u8 = &.{}, list: []Mapping = &.{}, }; pub const Symbol = struct { name: []const u8, addr: u64, size: u64 }; /// A row of a line table. `key` is the same for the same file of the same /// compilation unit, and `dir` and `name` together are its path. pub const Line = struct { key: usize, dir: []const u8, name: []const u8, line: u32, column: u32 }; pub const Module = struct { path: []const u8, /// The lowest address it is mapped at, and the end of the highest. start: u64 = 0, end: u64 = 0, /// A target address minus this is the address in the file. bias: u64 = 0, /// Where the file says it starts running (an address in the file). entry: u64 = 0, /// Null when the file could not be read as ELF. file: ?std.debug.ElfFile = null, /// Functions and objects by address in the file. symbols: []Symbol = &.{}, dwarf_tried: bool = false, /// How many parameters each function takes, by its first address in /// the file: read from DWARF on first use. params: ?std.AutoHashMapUnmanaged(u64, u8) = null, /// The line tables, opened on first use. Null without debug info. fn dwarf(m: *Module, gpa: std.mem.Allocator) ?*Dwarf { const file = &(m.file orelse return null); const d = &(file.dwarf orelse return null); if (m.dwarf_tried) return d; m.dwarf_tried = true; open: { d.open(gpa, file.endian) catch break :open; d.populateRanges(gpa, file.endian) catch break :open; return d; } d.deinit(gpa); file.dwarf = null; return null; } /// The line table of the compilation unit that holds `pc`, an address in the file. fn lineTable(m: *Module, gpa: std.mem.Allocator, pc: u64) ?*const Dwarf.CompileUnit.SrcLocCache { const d = m.dwarf(gpa) orelse return null; // The ranges are sorted by start: the last that starts at or before pc. const after = std.sort.partitionPoint(Dwarf.Range, d.ranges.items, pc, struct { fn startsBefore(at: u64, r: Dwarf.Range) bool { return r.start <= at; } }.startsBefore); if (after == 0 or pc >= d.ranges.items[after - 1].end) return null; const cu = &d.compile_unit_list.items[d.ranges.items[after - 1].compile_unit_index]; d.populateSrcLocCache(gpa, m.file.?.endian, cu) catch return null; return &cu.src_loc_cache.?; } }; fn line(table: *const Dwarf.CompileUnit.SrcLocCache, entry: Dwarf.CompileUnit.SrcLocCache.LineEntry) ?Line { // File numbers start at 1 before DWARF 5. const index = std.math.sub(u32, entry.file, @intFromBool(table.version < 5)) catch return null; if (index >= table.files.len) return null; const file = &table.files[index]; if (file.dir_index >= table.directories.len) return null; return .{ .key = @intFromPtr(file), .dir = table.directories[file.dir_index].path, .name = file.path, .line = entry.line, .column = entry.column }; } pub fn deinit(s: *Symbols) void { for (s.modules.items) |*m| { if (m.file) |*f| f.deinit(s.gpa); if (m.params) |*p| p.deinit(s.gpa); s.gpa.free(m.symbols); s.gpa.free(m.path); } s.modules.deinit(s.gpa); s.free(s.maps); } /// Reads the process's mappings again and loads the modules that are new. /// Returns the mappings as they were, for the caller to compare and `free`. pub fn refresh(s: *Symbols, pid: std.os.linux.pid_t) !Maps { var path_buf: [32]u8 = undefined; const path = std.fmt.bufPrint(&path_buf, "/proc/{d}/maps", .{pid}) catch unreachable; const file = try std.Io.Dir.cwd().openFile(s.io, path, .{}); defer file.close(s.io); var read_buf: [4096]u8 = undefined; var reader = file.readerStreaming(s.io, &read_buf); const new: Maps = new: { const text = try reader.interface.allocRemaining(s.gpa, .unlimited); errdefer s.gpa.free(text); var list: std.ArrayList(Mapping) = .empty; errdefer list.deinit(s.gpa); var lines = std.mem.tokenizeScalar(u8, text, '\n'); // 7f0000000000-7f0000001000 r-xp 00002000 08:01 1234 /usr/lib/libc.so.6 while (lines.next()) |l| { var fields = std.mem.tokenizeScalar(u8, l, ' '); const range = fields.next() orelse continue; const perms = fields.next() orelse continue; const offset = fields.next() orelse continue; _ = fields.next(); // device _ = fields.next(); // inode const dash = std.mem.indexOfScalar(u8, range, '-') orelse continue; try list.append(s.gpa, .{ .start = std.fmt.parseInt(u64, range[0..dash], 16) catch continue, .end = std.fmt.parseInt(u64, range[dash + 1 ..], 16) catch continue, .prot = @as(u8, @intFromBool(perms[0] == 'r')) | @as(u8, @intFromBool(perms[1] == 'w')) << 1 | @as(u8, @intFromBool(perms[2] == 'x')) << 2, .offset = std.fmt.parseInt(u64, offset, 16) catch continue, .name = fields.rest(), }); } break :new .{ .text = text, .list = try list.toOwnedSlice(s.gpa) }; }; const old = s.maps; s.maps = new; s.row = .{}; // Failing below, the mappings are as they were. errdefer { s.free(new); s.maps = old; } // A module is a file with code mapped from it. for (s.maps.list) |m| { if (m.prot & 4 == 0 or !std.mem.startsWith(u8, m.name, "/")) continue; if (s.module(m.name) == null) try s.load(m.name); } for (s.modules.items) |*mod| { mod.start = std.math.maxInt(u64); mod.end = 0; for (s.maps.list) |m| { if (!std.mem.eql(u8, m.name, mod.path)) continue; mod.start = @min(mod.start, m.start); mod.end = @max(mod.end, m.end); } if (mod.end == 0) mod.start = 0; // unmapped since } return old; } pub fn free(s: *Symbols, maps: Maps) void { s.gpa.free(maps.list); s.gpa.free(maps.text); } fn module(s: *Symbols, path: []const u8) ?*Module { for (s.modules.items) |*m| { if (std.mem.eql(u8, m.path, path)) return m; } return null; } fn load(s: *Symbols, path: []const u8) !void { try s.modules.ensureUnusedCapacity(s.gpa, 1); var m: Module = .{ .path = try s.gpa.dupe(u8, path) }; errdefer s.gpa.free(m.path); // A file that is gone or is no ELF stays a module, with nothing known about it. if (std.Io.Dir.cwd().openFile(s.io, path, .{})) |file| { defer file.close(s.io); m.file = std.debug.ElfFile.load(s.gpa, s.io, file, null, &.none) catch null; } else |_| {} if (m.file) |*f| { errdefer f.deinit(s.gpa); m.symbols = readSymbols(s.gpa, f.mapped_file) catch |err| switch (err) { error.OutOfMemory => |e| return e, else => &.{}, }; if (firstLoad(f.mapped_file)) |first| { m.entry = first.entry; // Where the file's first segment landed tells where all of it did. for (s.maps.list) |map| { if (std.mem.eql(u8, map.name, path) and map.offset == first.load.offset & ~@as(u64, 4095)) { m.bias = map.start -% (first.load.vaddr & ~@as(u64, 4095)); break; } } } } s.modules.appendAssumeCapacity(m); } /// The file's entry point and its first loaded segment. fn firstLoad(bytes: []const u8) ?struct { entry: u64, load: elf.Elf64.Phdr } { var r: std.Io.Reader = .fixed(bytes); const header = elf.Header.read(&r) catch return null; var it = header.iterateProgramHeadersBuffer(bytes); while (it.next() catch return null) |ph| { if (ph.type == .LOAD) return .{ .entry = header.entry, .load = ph }; } return null; } /// The functions and objects of .symtab, or of .dynsym in a stripped file, sorted by address. fn readSymbols(gpa: std.mem.Allocator, bytes: []const u8) ![]Symbol { var r: std.Io.Reader = .fixed(bytes); const header = try elf.Header.read(&r); if (!header.is_64 or header.endian != .little) return &.{}; var table: ?elf.Elf64_Shdr = null; var it = header.iterateSectionHeadersBuffer(bytes); while (try it.next()) |sh| { if (sh.sh_type == elf.SHT_SYMTAB or (sh.sh_type == elf.SHT_DYNSYM and table == null)) table = sh; } const sh = table orelse return &.{}; const names_at = header.shoff + @as(u64, sh.sh_link) * header.shentsize; if (names_at + @sizeOf(elf.Elf64_Shdr) > bytes.len or sh.sh_offset + sh.sh_size > bytes.len) return error.TruncatedElfFile; const names_sh = std.mem.bytesToValue(elf.Elf64_Shdr, bytes[names_at..][0..@sizeOf(elf.Elf64_Shdr)]); if (names_sh.sh_offset + names_sh.sh_size > bytes.len) return error.TruncatedElfFile; const names = bytes[names_sh.sh_offset..][0..names_sh.sh_size]; var out: std.ArrayList(Symbol) = .empty; errdefer out.deinit(gpa); const count = sh.sh_size / @sizeOf(elf.Elf64.Sym); for (std.mem.bytesAsSlice(elf.Elf64.Sym, bytes[sh.sh_offset..][0 .. count * @sizeOf(elf.Elf64.Sym)])) |sym| { if (sym.shndx == elf.SHN_UNDEF or sym.name == 0 or sym.name >= names.len) continue; switch (sym.info.type) { .FUNC, .OBJECT, .GNU_IFUNC, .NOTYPE => {}, else => continue, } try out.append(gpa, .{ .name = std.mem.sliceTo(names[sym.name..], 0), .addr = sym.value, .size = sym.size }); } std.mem.sortUnstable(Symbol, out.items, {}, struct { fn lessThan(_: void, a: Symbol, b: Symbol) bool { return a.addr < b.addr; } }.lessThan); return out.toOwnedSlice(gpa); } /// Where the program itself starts running, after its loader: the /// executable is the first module, mapped lowest. pub fn entryPoint(s: *const Symbols) ?u64 { if (s.modules.items.len == 0 or s.modules.items[0].file == null) return null; return s.modules.items[0].entry + s.modules.items[0].bias; } pub fn mappingAt(s: *const Symbols, addr: u64) ?Mapping { for (s.maps.list) |m| { if (addr >= m.start and addr < m.end) return m; } return null; } pub fn moduleAt(s: *Symbols, addr: u64) ?*Module { for (s.modules.items) |*m| { if (addr >= m.start and addr < m.end) return m; } return null; } /// The symbol that holds `addr`. pub fn symbolAt(s: *Symbols, addr: u64) ?Symbol { const m = s.moduleAt(addr) orelse return null; const pc = addr - m.bias; const after = std.sort.partitionPoint(Symbol, m.symbols, pc, struct { fn startsBefore(at: u64, sym: Symbol) bool { return sym.addr <= at; } }.startsBefore); // The nearest below may be a label inside the function, or an alias of it: look a few back. var i = after; while (i > 0 and after - i < 8) : (i -= 1) { const sym = m.symbols[i - 1]; if (pc - sym.addr < @max(sym.size, 1)) return .{ .name = sym.name, .addr = sym.addr + m.bias, .size = sym.size }; } return null; } /// A symbol by name: the executable's first, then the libraries'. As the /// linker has it, else (with `demangle`) as the source does. pub fn find(s: *Symbols, name: []const u8) ?Symbol { var buf: [1024]u8 = undefined; for ([_]bool{ false, true }) |source| { if (source and s.demangle == null) break; for (s.modules.items) |*m| { if (m.end == 0) continue; for (m.symbols) |sym| { const have = if (source) s.sourceName(sym.name, &buf) orelse continue else sym.name; if (std.mem.eql(u8, have, name)) return .{ .name = sym.name, .addr = sym.addr + m.bias, .size = sym.size }; } } } return null; } /// The source line of the code at `addr`. pub fn lineAt(s: *Symbols, addr: u64) ?Line { // Code runs along a row for a few instructions: the last answer is often this one's too. if (addr -% s.row.start < s.row.len) return s.row.line; const m = s.moduleAt(addr) orelse return null; const pc = addr - m.bias; const table = m.lineTable(s.gpa, pc) orelse return null; const rows = table.line_table.keys(); const after = std.sort.partitionPoint(u64, rows, pc, struct { fn startsBefore(at: u64, row: u64) bool { return row <= at; } }.startsBefore); if (after == 0) return null; s.row = .{ .start = rows[after - 1] + m.bias, .len = if (after < rows.len) rows[after] - rows[after - 1] else pc - rows[after - 1] + 1, .line = line(table, table.line_table.values()[after - 1]), }; return s.row.line; } /// The first code of `file`:`wanted`, or of the next line that has any. /// `file` matches by its last component. // shortcut: runs every compilation unit's line program, upgrade with an index by file name when a target is large (V8). pub fn lineAddress(s: *Symbols, file: []const u8, wanted: u32) ?u64 { var best: ?struct { line: u32, addr: u64 } = null; for (s.modules.items) |*m| { const d = m.dwarf(s.gpa) orelse continue; for (d.compile_unit_list.items) |*cu| { d.populateSrcLocCache(s.gpa, m.file.?.endian, cu) catch continue; const table = &cu.src_loc_cache.?; for (table.line_table.keys(), table.line_table.values()) |pc, entry| { if (entry.line < wanted) continue; const addr = pc + m.bias; if (best) |b| if (entry.line > b.line or (entry.line == b.line and addr >= b.addr)) continue; const l = line(table, entry) orelse continue; if (!std.mem.eql(u8, std.fs.path.basename(l.name), std.fs.path.basename(file))) continue; best = .{ .line = entry.line, .addr = addr }; } } } return if (best) |b| b.addr else null; } /// How many parameters the function that begins at `addr` takes, as its /// DWARF says (a variadic tail not counted). Null without debug info, or /// where no function it describes begins. pub fn parameters(s: *Symbols, addr: u64) ?u8 { const m = s.moduleAt(addr) orelse return null; const d = m.dwarf(s.gpa) orelse return null; if (m.params == null) { m.params = .empty; countParameters(s.gpa, d, &m.params.?) catch {}; } return m.params.?.get(addr - m.bias); } /// Each function's parameters, by its first address: the formal parameters /// among the children of each subprogram with code, in .debug_info. The /// units and their abbreviations are the ones `std.debug.Dwarf` read. fn countParameters(gpa: std.mem.Allocator, d: *const Dwarf, out: *std.AutoHashMapUnmanaged(u64, u8)) !void { const info = d.section(.debug_info) orelse return; const DW = std.dwarf; for (d.compile_unit_list.items) |*cu| { const table = for (d.abbrev_table_list.items) |*t| { if (t.offset == cu.abbrev_offset) break t; } else continue; const offset: u64 = if (cu.format == .@"64") 8 else 4; var r: std.Io.Reader = .fixed(info[0..@min(info.len, cu.offset + cu.size)]); // Past the unit's header: its length, version, (DWARF 5) unit type, // the abbreviations' offset and the address size. r.seek = @intCast(cu.offset + (if (offset == 8) @as(u64, 12) else 4) + 2 + offset + 1 + @intFromBool(cu.version >= 5)); var depth: usize = 0; // The function whose parameters are being counted, and how deep it is. var function: ?struct { pc: u64, depth: usize } = null; while (r.seek < r.buffer.len) { const code = try r.takeLeb128(u64); if (code == 0) { depth -|= 1; continue; } // Codes are mostly numbered from 1, in order. const abbrev = if (code <= table.abbrevs.len and table.abbrevs[code - 1].code == code) &table.abbrevs[code - 1] else for (table.abbrevs) |*a| { if (a.code == code) break a; } else return error.InvalidDebugInfo; var low_pc: ?u64 = null; for (abbrev.attrs) |attr| { const v = try formValue(&r, attr.form_id, cu); if (attr.id == DW.AT.low_pc) low_pc = switch (attr.form_id) { DW.FORM.addr => v, DW.FORM.addrx, DW.FORM.addrx1, DW.FORM.addrx2, DW.FORM.addrx3, DW.FORM.addrx4, DW.FORM.GNU_addr_index => debugAddr(d, cu, v), else => null, }; } const here = depth; if (abbrev.has_children) depth += 1; if (function) |f| if (here <= f.depth) { function = null; }; switch (abbrev.tag_id) { DW.TAG.subprogram => if (low_pc) |pc| { try out.put(gpa, pc, 0); if (abbrev.has_children) function = .{ .pc = pc, .depth = here }; }, DW.TAG.formal_parameter => if (function) |f| if (here == f.depth + 1) { out.getPtr(f.pc).?.* +|= 1; }, else => {}, } } } } /// The address at `index` of a unit's part of .debug_addr. fn debugAddr(d: *const Dwarf, cu: *const Dwarf.CompileUnit, index: u64) ?u64 { const table = d.section(.debug_addr) orelse return null; const at = cu.addr_base + index * cu.addr_size_bytes; if (cu.addr_size_bytes != 8 or at + 8 > table.len) return null; return std.mem.readInt(u64, table[@intCast(at)..][0..8], .little); } /// An attribute's value, read past: the number it is for the forms that /// are one, 0 for the rest (strings, blocks). fn formValue(r: *std.Io.Reader, form_id: u64, cu: *const Dwarf.CompileUnit) !u64 { const F = std.dwarf.FORM; const offset: usize = if (cu.format == .@"64") 8 else 4; var form = form_id; while (form == F.indirect) form = try r.takeLeb128(u64); return switch (form) { F.addr => try r.takeVarInt(u64, .little, cu.addr_size_bytes), F.data1, F.ref1, F.flag, F.strx1, F.addrx1 => try r.takeByte(), F.data2, F.ref2, F.strx2, F.addrx2 => try r.takeInt(u16, .little), F.strx3, F.addrx3 => try r.takeInt(u24, .little), F.data4, F.ref4, F.ref_sup4, F.strx4, F.addrx4 => try r.takeInt(u32, .little), F.data8, F.ref8, F.ref_sig8, F.ref_sup8 => try r.takeInt(u64, .little), F.udata, F.ref_udata, F.strx, F.addrx, F.loclistx, F.rnglistx, F.GNU_addr_index, F.GNU_str_index => try r.takeLeb128(u64), F.sdata => @bitCast(try r.takeLeb128(i64)), F.strp, F.line_strp, F.sec_offset, F.strp_sup, F.GNU_ref_alt, F.GNU_strp_alt => try r.takeVarInt(u64, .little, offset), F.ref_addr => try r.takeVarInt(u64, .little, if (cu.version == 2) cu.addr_size_bytes else offset), F.string => string: { _ = try r.takeSentinel(0); break :string 0; }, F.data16 => skip(r, 16), F.block1 => skip(r, try r.takeByte()), F.block2 => skip(r, try r.takeInt(u16, .little)), F.block4 => skip(r, try r.takeInt(u32, .little)), F.block, F.exprloc => skip(r, try r.takeLeb128(usize)), F.flag_present, F.implicit_const => 0, else => error.InvalidDebugInfo, }; } fn skip(r: *std.Io.Reader, n: usize) !u64 { try r.discardAll(n); return 0; } /// `addr` for a reader: "fib+12 (fib.c:5)", "libc.so.6!write+18", /// "libc.so.6+27781" where no symbol covers it, "[stack]+1f40". pub fn describe(s: *Symbols, w: *std.Io.Writer, addr: u64) !void { try w.print("{x} ", .{addr}); if (!try s.label(w, addr)) w.undo(1); if (s.lineAt(addr)) |l| try w.print(" ({s}:{d})", .{ std.fs.path.basename(l.name), l.line }); } /// A symbol's name as `demangle` makes it, its parameters left out. fn sourceName(s: *const Symbols, name: []const u8, buf: []u8) ?[]const u8 { const full = (s.demangle orelse return null)(name, buf) orelse return null; // They are the last parenthesis: "(anonymous namespace)::f(int) const". const close = std.mem.lastIndexOfScalar(u8, full, ')') orelse return full; var depth: usize = 0; var i = close + 1; while (i > 0) { i -= 1; if (full[i] == ')') depth += 1; if (full[i] == '(') { depth -= 1; if (depth == 0) return full[0..i]; } } return full; } test "a C++ name is shown without its parameters" { const s: Symbols = .{ .gpa = std.testing.allocator, .io = std.testing.io, .demangle = struct { fn as(name: []const u8, buf: []u8) ?[]const u8 { @memcpy(buf[0..name.len], name); return buf[0..name.len]; } }.as }; var buf: [128]u8 = undefined; for ([_][2][]const u8{ .{ "v8::internal::Heap::CollectGarbage(v8::internal::AllocationSpace)", "v8::internal::Heap::CollectGarbage" }, .{ "(anonymous namespace)::f(int) const", "(anonymous namespace)::f" }, .{ "S::operator()(int)", "S::operator()" }, .{ "v8::internal::FLAG_x", "v8::internal::FLAG_x" }, }) |case| try std.testing.expectEqualStrings(case[1], s.sourceName(case[0], &buf).?); } /// The name of `addr` alone: "fib+12", "libc.so.6!write+18", and where no /// symbol holds it how far into its module or mapping it is, in hex: /// "libc.so.6+2a1c9", "[stack]+1f40". False, and nothing written, for an /// address with none. pub fn label(s: *Symbols, w: *std.Io.Writer, addr: u64) !bool { if (s.moduleAt(addr)) |m| { const found = s.symbolAt(addr) orelse { // From where the module is mapped, not its address in the file: that is the address itself where it is not relocated. try w.print("{s}+{x}", .{ std.fs.path.basename(m.path), addr - m.start }); return true; }; // The executable is the first module mapped: its symbols need no prefix. if (m != &s.modules.items[0]) try w.print("{s}!", .{std.fs.path.basename(m.path)}); var buf: [1024]u8 = undefined; try w.print("{s}+{d}", .{ s.sourceName(found.name, &buf) orelse found.name, addr - found.addr }); return true; } const m = s.mappingAt(addr) orelse return false; if (m.name.len == 0) return false; try w.print("{s}+{x}", .{ m.name, addr - m.start }); return true; }