1//! Cross-platform abstraction for loading debug information into an in-memory
2//! format that supports queries such as "what is the source location of this
3//! virtual memory address?"
4//!
5//! Unlike `std.debug.SelfInfo`, this API does not assume the debug information
6//! in question happens to match the host CPU architecture, OS, or other target
7//! properties.
8const Info = @This();
9
10const std = @import("../std.zig");
11const Io = std.Io;
12const Allocator = std.mem.Allocator;
13const Path = std.Build.Cache.Path;
14const assert = std.debug.assert;
15const Coverage = std.debug.Coverage;
16const SourceLocation = std.debug.Coverage.SourceLocation;
17const ElfFile = std.debug.ElfFile;
18const MachOFile = std.debug.MachOFile;
19
20impl: union(enum) {
21 elf: ElfFile,
22 macho: MachOFile,
23},
24/// Externally managed, outlives this `Info` instance.
25coverage: *Coverage,
26
27pub const LoadError = error{
28 MissingDebugInfo,
29 UnsupportedDebugInfo,
30} || Io.File.OpenError || ElfFile.LoadError || MachOFile.Error || std.debug.Dwarf.ScanError;
31
32pub fn load(
33 gpa: Allocator,
34 io: Io,
35 path: Path,
36 coverage: *Coverage,
37 format: std.Target.ObjectFormat,
38 arch: std.Target.Cpu.Arch,
39) LoadError!Info {
40 switch (format) {
41 .elf => {
42 var file = try path.root_dir.handle.openFile(io, path.sub_path, .{});
43 defer file.close(io);
44
45 var elf_file: ElfFile = try .load(gpa, io, file, null, &.none);
46 errdefer elf_file.deinit(gpa);
47
48 if (elf_file.dwarf == null) return error.MissingDebugInfo;
49 try elf_file.dwarf.?.open(gpa, elf_file.endian);
50 try elf_file.dwarf.?.populateRanges(gpa, elf_file.endian);
51
52 return .{
53 .impl = .{ .elf = elf_file },
54 .coverage = coverage,
55 };
56 },
57 .macho => {
58 const path_str = try path.toString(gpa);
59 defer gpa.free(path_str);
60
61 var macho_file: MachOFile = try .load(gpa, io, path_str, arch);
62 errdefer macho_file.deinit(gpa);
63
64 return .{
65 .impl = .{ .macho = macho_file },
66 .coverage = coverage,
67 };
68 },
69 else => return error.UnsupportedDebugInfo,
70 }
71}
72
73pub fn deinit(info: *Info, gpa: Allocator) void {
74 switch (info.impl) {
75 .elf => |*ef| ef.deinit(gpa),
76 .macho => |*mf| mf.deinit(gpa),
77 }
78 info.* = undefined;
79}
80
81pub const ResolveAddressesError = Coverage.ResolveAddressesDwarfError || error{UnsupportedDebugInfo};
82
83/// Given an array of virtual memory addresses, sorted ascending, outputs a
84/// corresponding array of source locations.
85pub fn resolveAddresses(
86 info: *Info,
87 gpa: Allocator,
88 io: Io,
89 /// Asserts the addresses are in ascending order.
90 sorted_pc_addrs: []const u64,
91 /// Asserts its length equals length of `sorted_pc_addrs`.
92 output: []SourceLocation,
93) ResolveAddressesError!void {
94 assert(sorted_pc_addrs.len == output.len);
95 switch (info.impl) {
96 .elf => |*ef| return info.coverage.resolveAddressesDwarf(gpa, io, ef.endian, sorted_pc_addrs, output, &ef.dwarf.?),
97 .macho => |*mf| {
98 // Resolving all of the addresses at once unfortunately isn't so easy in Mach-O binaries
99 // due to split debug information. For now, we'll just resolve the addreses one by one.
100 for (sorted_pc_addrs, output) |pc_addr, *src_loc| {
101 const dwarf, const dwarf_pc_addr = mf.getDwarfForAddress(gpa, io, pc_addr) catch |err| switch (err) {
102 error.MissingDebugInfo => {
103 src_loc.* = .invalid;
104 continue;
105 },
106 error.InvalidMachO, error.InvalidDwarf => return error.InvalidDebugInfo,
107 else => |e| return e,
108 };
109 if (dwarf.ranges.items.len == 0) {
110 dwarf.populateRanges(gpa, .little) catch |err| switch (err) {
111 error.EndOfStream,
112 error.Overflow,
113 error.StreamTooLong,
114 error.ReadFailed,
115 => return error.InvalidDebugInfo,
116 else => |e| return e,
117 };
118 }
119 try info.coverage.resolveAddressesDwarf(gpa, io, .little, &.{dwarf_pc_addr}, src_loc[0..1], dwarf);
120 }
121 },
122 }
123}