//! 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 } = .{}, 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, /// 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); 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'. pub fn find(s: *Symbols, name: []const u8) ?Symbol { for (s.modules.items) |*m| { if (m.end == 0) continue; for (m.symbols) |sym| { if (std.mem.eql(u8, sym.name, 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; } /// `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 (s.moduleAt(addr)) |m| { const sym = s.symbolAt(addr); try w.writeAll(" "); // The executable is the first module mapped: its symbols need no prefix. if (sym == null or m != &s.modules.items[0]) try w.print("{s}!", .{std.fs.path.basename(m.path)}); if (sym) |found| try w.print("{s}+{d}", .{ found.name, addr - found.addr }) else try w.print("{x}", .{addr - m.bias}); } else if (s.mappingAt(addr)) |m| { if (m.name.len > 0) try w.print(" {s}+{x}", .{ m.name, addr - m.start }); } if (s.lineAt(addr)) |l| try w.print(" ({s}:{d})", .{ std.fs.path.basename(l.name), l.line }); }