跳转到内容

std.debug.SelfInfo.Windows

标准库Zig 0.17.0官方原文
源码std/debug/SelfInfo/Windows.zig

第 1 行

字段

lock: Io.RwLock
ntdll_handle: ?if (load_dll_notification_procs) *anyopaque else noreturn
notification_cookie: ?LDR.DLL_NOTIFICATION.COOKIE
modules: std.ArrayList(Module)

std.debug.SelfInfo.Windows.Allocator

别名

第 717 行

别名目标 std.mem.Allocator

std.debug.SelfInfo.Windows.builtin

常量

第 726 行

std.debug.SelfInfo.Windows.can_unwind

常量

第 70 行

bool

std.debug.SelfInfo.Windows.coff

别名

第 721 行

别名目标 std.coff

std.debug.SelfInfo.Windows.deinit

函数

第 12 行

pub fn deinit(si: *SelfInfo, io: Io) void

参数

si: *SelfInfo
io: Io

std.debug.SelfInfo.Windows.dllNotification

函数

第 693 行

fn dllNotification( reason: LDR.DLL_NOTIFICATION.REASON, data: *const LDR.DLL_NOTIFICATION.DATA, context: ?*anyopaque, ) callconv(.winapi) void

参数

reason: LDR.DLL_NOTIFICATION.REASON
data: *const LDR.DLL_NOTIFICATION.DATA
context: ?*anyopaque

std.debug.SelfInfo.Windows.Dwarf

别名

第 718 行

别名目标 std.debug.Dwarf

std.debug.SelfInfo.Windows.Error

别名

第 720 行

别名目标 std.debug.SelfInfoError

std.debug.SelfInfo.Windows.findModule

函数

第 634 行

假定我们已经持有 si.lock。

fn findModule(si: *SelfInfo, gpa: Allocator, address: usize) error{ MissingDebugInfo, OutOfMemory, Unexpected }!*Module

参数

si: *SelfInfo
gpa: Allocator
address: usize

错误

MissingDebugInfo
OutOfMemory
Unexpected

std.debug.SelfInfo.Windows.fs

别名

第 722 行

别名目标 std.fs

std.debug.SelfInfo.Windows.getModuleName

函数

第 51 行

pub fn getModuleName(si: *SelfInfo, io: Io, address: usize) Error![]const u8

参数

si: *SelfInfo
io: Io
address: usize

错误

Canceled SelfInfoError
InvalidDebugInfo SelfInfoError

所需调试信息无效或已损坏。

MissingDebugInfo SelfInfoError

无法找到所需调试信息。

OutOfMemory SelfInfoError
ReadFailed SelfInfoError

由于某个 I/O 错误,无法从磁盘读取所需调试信息。

Unexpected SelfInfoError
UnsupportedDebugInfo SelfInfoError

已找到所需调试信息,且其可能有效,但此实现不支持它。

std.debug.SelfInfo.Windows.getModuleSlide

函数

第 62 行

pub fn getModuleSlide(si: *SelfInfo, io: Io, address: usize) Error!usize

参数

si: *SelfInfo
io: Io
address: usize

错误

Canceled SelfInfoError
InvalidDebugInfo SelfInfoError

所需调试信息无效或已损坏。

MissingDebugInfo SelfInfoError

无法找到所需调试信息。

OutOfMemory SelfInfoError
ReadFailed SelfInfoError

由于某个 I/O 错误,无法从磁盘读取所需调试信息。

Unexpected SelfInfoError
UnsupportedDebugInfo SelfInfoError

已找到所需调试信息,且其可能有效,但此实现不支持它。

std.debug.SelfInfo.Windows.getNtdllProc

函数

第 663 行

inline fn getNtdllProc( si: *SelfInfo, comptime proc: std.meta.DeclEnum(windows.ntdll), ) !@TypeOf(&@field(windows.ntdll, @tagName(proc)))

参数

std.debug.SelfInfo.Windows.getSymbols

函数

第 28 行

pub fn getSymbols( si: *SelfInfo, io: Io, symbol_allocator: Allocator, text_arena: Allocator, address: usize, resolve_inline_callers: bool, symbols: *std.ArrayList(std.debug.Symbol), ) Error!void

参数

si: *SelfInfo
io: Io
symbol_allocator: Allocator
text_arena: Allocator
address: usize
resolve_inline_callers: bool
symbols: *std.ArrayList(std.debug.Symbol)

错误

Canceled SelfInfoError
InvalidDebugInfo SelfInfoError

所需调试信息无效或已损坏。

MissingDebugInfo SelfInfoError

无法找到所需调试信息。

OutOfMemory SelfInfoError
ReadFailed SelfInfoError

由于某个 I/O 错误,无法从磁盘读取所需调试信息。

Unexpected SelfInfoError
UnsupportedDebugInfo SelfInfoError

已找到所需调试信息,且其可能有效,但此实现不支持它。

std.debug.SelfInfo.Windows.init

常量

第 6 行

SelfInfo

std.debug.SelfInfo.Windows.Io

别名

第 716 行

别名目标 std.Io

std.debug.SelfInfo.Windows.LDR

别名

第 724 行

别名目标 std.os.windows.LDR

std.debug.SelfInfo.Windows.load_dll_notification_procs

常量

第 728 行

std.debug.SelfInfo.Windows.loadNtdllProc

函数

第 672 行

fn loadNtdllProc(si: *SelfInfo, name: []const u8) Io.UnexpectedError!*anyopaque

参数

si: *SelfInfo
name: []const u8

错误

Unexpected

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.debug.SelfInfo.Windows.Module

容器

第 215 行

字段

entry: *const LDR.DATA_TABLE_ENTRY
name: ?[]const u8
di: ?(Error!DebugInfo)

std.debug.SelfInfo.Windows.Module.DebugInfo

容器

第 220 行

字段

arena: std.heap.ArenaAllocator.State
coff_image_base: u64
mapped_file: ?MappedFile
dwarf: ?Dwarf
pdb: ?Pdb
coff_section_headers: []coff.SectionHeader

std.debug.SelfInfo.Windows.Module.DebugInfo.deinit

函数

第 246 行

fn deinit(di: *DebugInfo, gpa: Allocator, io: Io) void

参数

di: *DebugInfo
gpa: Allocator
io: Io

std.debug.SelfInfo.Windows.Module.DebugInfo.getSymbols

函数

第 258 行

fn getSymbols( di: *DebugInfo, symbol_allocator: Allocator, text_arena: Allocator, vaddr: usize, resolve_inline_callers: bool, symbols: *std.ArrayList(std.debug.Symbol), ) Error!void

参数

di: *DebugInfo
symbol_allocator: Allocator
text_arena: Allocator
vaddr: usize
resolve_inline_callers: bool
symbols: *std.ArrayList(std.debug.Symbol)

错误

Canceled SelfInfoError
InvalidDebugInfo SelfInfoError

所需调试信息无效或已损坏。

MissingDebugInfo SelfInfoError

无法找到所需调试信息。

OutOfMemory SelfInfoError
ReadFailed SelfInfoError

由于某个 I/O 错误,无法从磁盘读取所需调试信息。

Unexpected SelfInfoError
UnsupportedDebugInfo SelfInfoError

已找到所需调试信息,且其可能有效,但此实现不支持它。

std.debug.SelfInfo.Windows.Module.DebugInfo.MappedFile

容器

第 228 行

字段

file: Io.File
section_handle: windows.HANDLE
section_view: []const u8

std.debug.SelfInfo.Windows.Module.DebugInfo.MappedFile.deinit

函数

第 232 行

fn deinit(mf: *const MappedFile, io: Io) void

参数

mf: *const MappedFile
io: Io

std.debug.SelfInfo.Windows.Module.deinit

函数

第 392 行

fn deinit(module: *Module, gpa: Allocator, io: Io) void

参数

module: *Module
gpa: Allocator
io: Io

std.debug.SelfInfo.Windows.Module.getDebugInfo

函数

第 398 行

fn getDebugInfo(module: *Module, gpa: Allocator, io: Io) Error!*DebugInfo

参数

module: *Module
gpa: Allocator
io: Io

错误

Canceled SelfInfoError
InvalidDebugInfo SelfInfoError

所需调试信息无效或已损坏。

MissingDebugInfo SelfInfoError

无法找到所需调试信息。

OutOfMemory SelfInfoError
ReadFailed SelfInfoError

由于某个 I/O 错误,无法从磁盘读取所需调试信息。

Unexpected SelfInfoError
UnsupportedDebugInfo SelfInfoError

已找到所需调试信息,且其可能有效,但此实现不支持它。

std.debug.SelfInfo.Windows.Module.loadDebugInfo

函数

第 402 行

fn loadDebugInfo(module: *const Module, gpa: Allocator, io: Io) Error!DebugInfo

参数

module: *const Module
gpa: Allocator
io: Io

错误

Canceled SelfInfoError
InvalidDebugInfo SelfInfoError

所需调试信息无效或已损坏。

MissingDebugInfo SelfInfoError

无法找到所需调试信息。

OutOfMemory SelfInfoError
ReadFailed SelfInfoError

由于某个 I/O 错误,无法从磁盘读取所需调试信息。

Unexpected SelfInfoError
UnsupportedDebugInfo SelfInfoError

已找到所需调试信息,且其可能有效,但此实现不支持它。

std.debug.SelfInfo.Windows.native_endian

常量

第 727 行

std.debug.SelfInfo.Windows.Pdb

别名

第 719 行

别名目标 std.debug.Pdb

std.debug.SelfInfo.Windows.SelfInfo

别名

第 740 行

别名目标 std.debug.SelfInfo.Windows

std.debug.SelfInfo.Windows.std

别名

第 715 行

别名目标 std

std.debug.SelfInfo.Windows.UnwindContext

容器

第 97 行

字段

pc: usize
cur: windows.CONTEXT
history_table: windows.UNWIND_HISTORY_TABLE

std.debug.SelfInfo.Windows.UnwindContext.deinit

函数

第 171 行

pub fn deinit(ctx: *UnwindContext) void

参数

std.debug.SelfInfo.Windows.UnwindContext.getFp

函数

第 174 行

pub fn getFp(ctx: *UnwindContext) usize

参数

std.debug.SelfInfo.Windows.UnwindContext.init

函数

第 101 行

pub fn init(ctx: *const std.debug.cpu_context.Native) UnwindContext

参数

ctx: *const std.debug.cpu_context.Native

std.debug.SelfInfo.Windows.unwindFrame

函数

第 178 行

pub fn unwindFrame(si: *SelfInfo, io: Io, context: *UnwindContext) Error!usize

参数

si: *SelfInfo
io: Io
context: *UnwindContext

错误

Canceled SelfInfoError
InvalidDebugInfo SelfInfoError

所需调试信息无效或已损坏。

MissingDebugInfo SelfInfoError

无法找到所需调试信息。

OutOfMemory SelfInfoError
ReadFailed SelfInfoError

由于某个 I/O 错误,无法从磁盘读取所需调试信息。

Unexpected SelfInfoError
UnsupportedDebugInfo SelfInfoError

已找到所需调试信息,且其可能有效,但此实现不支持它。

std.debug.SelfInfo.Windows.windows

别名

第 723 行

别名目标 std.os.windows

源码

std/debug/SelfInfo/Windows.zig

lock: Io.RwLock,
ntdll_handle: ?if (load_dll_notification_procs) *anyopaque else noreturn,
notification_cookie: ?LDR.DLL_NOTIFICATION.COOKIE,
modules: std.ArrayList(Module),

pub const init: SelfInfo = .{
    .lock = .init,
    .ntdll_handle = null,
    .notification_cookie = null,
    .modules = .empty,
};
pub fn deinit(si: *SelfInfo, io: Io) void {
    const gpa = std.debug.getDebugInfoAllocator();
    if (si.notification_cookie) |cookie| unregister: {
        switch ((si.getNtdllProc(.LdrUnregisterDllNotification) catch break :unregister)(cookie)) {
            .SUCCESS => {},
            else => |status| windows.unexpectedStatus(status) catch break :unregister,
        }
    }
    if (si.ntdll_handle) |handle| switch (windows.ntdll.LdrUnloadDll(handle)) {
        .SUCCESS => {},
        else => |status| windows.unexpectedStatus(status) catch {},
    };
    for (si.modules.items) |*module| module.deinit(gpa, io);
    si.modules.deinit(gpa);
}

pub fn getSymbols(
    si: *SelfInfo,
    io: Io,
    symbol_allocator: Allocator,
    text_arena: Allocator,
    address: usize,
    resolve_inline_callers: bool,
    symbols: *std.ArrayList(std.debug.Symbol),
) Error!void {
    const gpa = std.debug.getDebugInfoAllocator();
    try si.lock.lockShared(io);
    defer si.lock.unlockShared(io);
    const module = try si.findModule(gpa, address);
    const di = try module.getDebugInfo(gpa, io);
    return di.getSymbols(
        symbol_allocator,
        text_arena,
        address - @intFromPtr(module.entry.DllBase),
        resolve_inline_callers,
        symbols,
    );
}

pub fn getModuleName(si: *SelfInfo, io: Io, address: usize) Error![]const u8 {
    const gpa = std.debug.getDebugInfoAllocator();
    try si.lock.lockShared(io);
    defer si.lock.unlockShared(io);
    const module = try si.findModule(gpa, address);
    return module.name orelse {
        const name = try std.unicode.wtf16LeToWtf8Alloc(gpa, module.entry.BaseDllName.slice());
        module.name = name;
        return name;
    };
}
pub fn getModuleSlide(si: *SelfInfo, io: Io, address: usize) Error!usize {
    const gpa = std.debug.getDebugInfoAllocator();
    try si.lock.lockShared(io);
    defer si.lock.unlockShared(io);
    const module = try si.findModule(gpa, address);
    return module.base_address;
}

pub const can_unwind: bool = switch (builtin.cpu.arch) {
    else => true,
    // x86 上不存在 `RtlVirtualUnwind`。理论上可以改用 `RtlCaptureStackBackTrace`,
    // 但在 x86 上,该函数实际上只是借助 esp 进行帧指针展开!
    // 很难找到能证实这一点的实现细节;我找到的最权威来源
    // 是 LLVM 邮件列表中 2020/08/16 的一封邮件,其中写道:
    //
    // > x86 不具备多数架构意义上用于恢复寄存器的
    // > “展开器”;它只有一个参与 SEH 的帧链表,
    // > 这些帧希望在动态展开操作中得到调用,因此 RtlCaptureStackBackTrace
    // > 假定使用基于 EBP 的栈帧,并在 x86 上遍历基于 EBP 的帧链。
    // > 并非所有 x86 代码均使用基于 EBP 的栈帧,因此尽管操作系统通常
    // > 按这种方式构建,仍然可能遇到将 EBP 用作
    // > 通用寄存器的外部代码;此时这种用于获取栈回溯的
    // > 展开尝试将会失败。
    //
    // 不过,只需使用 `-fomit-frame-pointer -OReleaseFast`
    // 编译一些代码,再观察 `RtlCaptureStackBackTrace` 在该程序中返回
    // 空回溯,就能有效证实此假设。注意,不使用 `-OReleaseFast`
    // 或类似选项时,LLVM 似乎不愿改写 ebp,因此返回的回溯
    // 只包含 kernel32/ntdll 的栈帧,而不包含程序自身的栈帧。不要被误导:
    // 这只是巧合!
    //
    // 总之,x86-windows 上唯一的栈遍历原语是帧指针展开。我们
    // *可以*通过 `RtlCaptureStackBackTrace` 请求 Microsoft 代为执行,但直接使用 `std.debug` 中现有的帧指针展开器更合适!
    .x86 => false,
};
pub const UnwindContext = struct {
    pc: usize,
    cur: windows.CONTEXT,
    history_table: windows.UNWIND_HISTORY_TABLE,
    pub fn init(ctx: *const std.debug.cpu_context.Native) UnwindContext {
        return .{
            .pc = @returnAddress(),
            .cur = switch (builtin.cpu.arch) {
                .x86_64 => std.mem.zeroInit(windows.CONTEXT, .{
                    .Rax = ctx.gprs.get(.rax),
                    .Rcx = ctx.gprs.get(.rcx),
                    .Rdx = ctx.gprs.get(.rdx),
                    .Rbx = ctx.gprs.get(.rbx),
                    .Rsp = ctx.gprs.get(.rsp),
                    .Rbp = ctx.gprs.get(.rbp),
                    .Rsi = ctx.gprs.get(.rsi),
                    .Rdi = ctx.gprs.get(.rdi),
                    .R8 = ctx.gprs.get(.r8),
                    .R9 = ctx.gprs.get(.r9),
                    .R10 = ctx.gprs.get(.r10),
                    .R11 = ctx.gprs.get(.r11),
                    .R12 = ctx.gprs.get(.r12),
                    .R13 = ctx.gprs.get(.r13),
                    .R14 = ctx.gprs.get(.r14),
                    .R15 = ctx.gprs.get(.r15),
                    .Rip = ctx.gprs.get(.rip),
                }),
                .aarch64 => .{
                    .ContextFlags = 0,
                    .Cpsr = 0,
                    .DUMMYUNIONNAME = .{ .X = ctx.x },
                    .Sp = ctx.sp,
                    .Pc = ctx.pc,
                    .V = @splat(.{ .B = @splat(0) }),
                    .Fpcr = 0,
                    .Fpsr = 0,
                    .Bcr = @splat(0),
                    .Bvr = @splat(0),
                    .Wcr = @splat(0),
                    .Wvr = @splat(0),
                },
                .thumb => .{
                    .ContextFlags = 0,
                    .R0 = ctx.r[0],
                    .R1 = ctx.r[1],
                    .R2 = ctx.r[2],
                    .R3 = ctx.r[3],
                    .R4 = ctx.r[4],
                    .R5 = ctx.r[5],
                    .R6 = ctx.r[6],
                    .R7 = ctx.r[7],
                    .R8 = ctx.r[8],
                    .R9 = ctx.r[9],
                    .R10 = ctx.r[10],
                    .R11 = ctx.r[11],
                    .R12 = ctx.r[12],
                    .Sp = ctx.r[13],
                    .Lr = ctx.r[14],
                    .Pc = ctx.r[15],
                    .Cpsr = 0,
                    .Fpcsr = 0,
                    .Padding = 0,
                    .DUMMYUNIONNAME = .{ .S = @splat(0) },
                    .Bvr = @splat(0),
                    .Bcr = @splat(0),
                    .Wvr = @splat(0),
                    .Wcr = @splat(0),
                    .Padding2 = @splat(0),
                },
                else => comptime unreachable,
            },
            .history_table = std.mem.zeroes(windows.UNWIND_HISTORY_TABLE),
        };
    }
    pub fn deinit(ctx: *UnwindContext) void {
        _ = ctx;
    }
    pub fn getFp(ctx: *UnwindContext) usize {
        return ctx.cur.getRegs().bp;
    }
};
pub fn unwindFrame(si: *SelfInfo, io: Io, context: *UnwindContext) Error!usize {
    _ = si;
    _ = io;

    const current_regs = context.cur.getRegs();
    var image_base: usize = undefined;
    if (windows.ntdll.RtlLookupFunctionEntry(current_regs.ip, &image_base, &context.history_table)) |runtime_function| {
        var handler_data: ?*anyopaque = null;
        var establisher_frame: usize = undefined;
        _ = windows.ntdll.RtlVirtualUnwind(
            windows.UNW_FLAG_NHANDLER,
            image_base,
            current_regs.ip,
            runtime_function,
            &context.cur,
            &handler_data,
            &establisher_frame,
            null,
        );
    } else {
        // 叶函数
        context.cur.setIp(@as(*const usize, @ptrFromInt(current_regs.sp)).*);
        context.cur.setSp(current_regs.sp + @sizeOf(usize));
    }

    const next_regs = context.cur.getRegs();
    const tib = &windows.teb().NtTib;
    if (next_regs.sp < @intFromPtr(tib.StackLimit) or next_regs.sp > @intFromPtr(tib.StackBase)) {
        context.pc = 0;
        return 0;
    }
    // 类似 `DwarfUnwindContext.unwindFrame`,若 `call` 是此函数最后一条指令,
    // 使 `next_regs.ip` 位于函数末尾之后一字节,则调整下一次查找的 pc。
    context.pc = next_regs.ip -| 1;
    return next_regs.ip;
}

const Module = struct {
    entry: *const LDR.DATA_TABLE_ENTRY,
    name: ?[]const u8,
    di: ?(Error!DebugInfo),

    const DebugInfo = struct {
        arena: std.heap.ArenaAllocator.State,
        coff_image_base: u64,
        mapped_file: ?MappedFile,
        dwarf: ?Dwarf,
        pdb: ?Pdb,
        coff_section_headers: []coff.SectionHeader,

        const MappedFile = struct {
            file: Io.File,
            section_handle: windows.HANDLE,
            section_view: []const u8,
            fn deinit(mf: *const MappedFile, io: Io) void {
                const process_handle = windows.GetCurrentProcess();
                switch (windows.ntdll.NtUnmapViewOfSection(
                    process_handle,
                    @constCast(mf.section_view.ptr),
                )) {
                    .SUCCESS => {},
                    else => |status| windows.unexpectedStatus(status) catch {},
                }
                windows.CloseHandle(mf.section_handle);
                mf.file.close(io);
            }
        };

        fn deinit(di: *DebugInfo, gpa: Allocator, io: Io) void {
            if (di.dwarf) |*dwarf| dwarf.deinit(gpa);
            if (di.pdb) |*pdb| {
                pdb.file_reader.file.close(io);
                pdb.deinit();
            }
            if (di.mapped_file) |*mf| mf.deinit(io);

            var arena = di.arena.promote(gpa);
            arena.deinit();
        }

        fn getSymbols(
            di: *DebugInfo,
            symbol_allocator: Allocator,
            text_arena: Allocator,
            vaddr: usize,
            resolve_inline_callers: bool,
            symbols: *std.ArrayList(std.debug.Symbol),
        ) Error!void {
            pdb: {
                const pdb = &(di.pdb orelse break :pdb);
                var coff_section: *align(1) const coff.SectionHeader = undefined;
                const mod_index = for (pdb.sect_contribs) |sect_contrib| {
                    if (sect_contrib.section > di.coff_section_headers.len) continue;
                    // 注意,SectionContribEntry.Section 从 1 开始编号。
                    coff_section = &di.coff_section_headers[sect_contrib.section - 1];

                    const vaddr_start = coff_section.virtual_address + sect_contrib.offset;
                    const vaddr_end = vaddr_start + sect_contrib.size;
                    if (vaddr >= vaddr_start and vaddr < vaddr_end) {
                        break sect_contrib.module_index;
                    }
                } else {
                    // 没有可添加到地址的信息
                    break :pdb;
                };
                const module = pdb.getModule(mod_index) catch |err| switch (err) {
                    error.InvalidDebugInfo,
                    error.MissingDebugInfo,
                    error.OutOfMemory,
                    => |e| return e,

                    error.ReadFailed,
                    error.EndOfStream,
                    => return error.InvalidDebugInfo,
                } orelse {
                    return error.InvalidDebugInfo; // 错误的模块索引
                };

                const addr = vaddr - coff_section.virtual_address;
                const maybe_proc = pdb.getProcSym(module, addr);
                const compile_unit_name = fs.path.basename(module.obj_file_name);
                const symbols_top = symbols.items.len;
                if (maybe_proc) |proc| {
                    const offset_in_func = addr - proc.code_offset;
                    var last_inlinee: ?u32 = null;
                    var iter = pdb.getInlinees(module, proc);
                    while (iter.next(module)) |inline_site| {
                        // 过滤重复的内联位置。若移除此检查,llvm-addr2line 等工具也会在相同情况下输出重复位置,这说明重复存在于底层数据中,并非解析器缺陷。
                        // 由于内联位置实际上不能引用自身,此处不会丢失有用信息。
                        //
                        //
                        //
                        if (inline_site.inlinee == last_inlinee) continue;

                        // 若地址指向此位置内部,获取它指向的
                        // 源码位置
                        var line_iter = pdb.getInlineeSourceLines(module, inline_site.inlinee);
                        while (line_iter.next()) |inlinee_src_line| {
                            const maybe_loc = pdb.getInlineSiteSourceLocation(
                                text_arena,
                                module,
                                inline_site,
                                inlinee_src_line,
                                offset_in_func,
                            ) catch continue;
                            const loc = maybe_loc orelse continue;

                            // 若不尝试解析内联调用者,且匹配到新的内联位置,
                            // 则应覆盖之前追加的结果。
                            //
                            if (!resolve_inline_callers and inline_site.inlinee != last_inlinee) {
                                symbols.items.len = symbols_top;
                            }

                            // 仅在解析内联调用方时解析名称,否则等到处理完成,以免重复工作。
                            //
                            const name = if (resolve_inline_callers)
                                pdb.findInlineeName(inline_site.inlinee)
                            else
                                null;

                            try symbols.append(symbol_allocator, .{
                                .name = name,
                                .compile_unit_name = compile_unit_name,
                                .source_location = loc,
                            });

                            last_inlinee = inline_site.inlinee;
                        }
                    }

                    if (resolve_inline_callers) {
                        // 内联调用点在 pdb 中按相反顺序存储,因此在此反转匹配调用点。
                        // 也可利用 parent 字段确定顺序,
                        // 但那会引入看似不必要的
                        // 复杂度。
                        std.mem.reverse(std.debug.Symbol, symbols.items);
                    } else if (last_inlinee) |inlinee| {
                        // 如果不解析内联调用方,所有结果将具有
                        // 相同的内联位置,最后只需解析一次其名称。
                        const name = pdb.findInlineeName(inlinee);
                        for (symbols.items) |*symbol| symbol.name = name;
                    }
                }

                // 若还有容纳另一个符号的空间,则添加实际过程
                if (resolve_inline_callers or symbols.items.len == 0) {
                    try symbols.append(symbol_allocator, .{
                        .name = if (maybe_proc) |proc| pdb.getSymbolName(proc) else null,
                        .compile_unit_name = compile_unit_name,
                        .source_location = pdb.getLineNumberInfo(text_arena, module, addr) catch null,
                    });
                }

                return;
            }

            dwarf: {
                const dwarf = &(di.dwarf orelse break :dwarf);
                const addr = vaddr + di.coff_image_base;
                return dwarf.getSymbols(
                    symbol_allocator,
                    text_arena,
                    native_endian,
                    addr,
                    resolve_inline_callers,
                    symbols,
                );
            }

            return error.MissingDebugInfo;
        }
    };

    fn deinit(module: *Module, gpa: Allocator, io: Io) void {
        if (module.name) |name| gpa.free(name);
        if (module.di) |*di_or_err| if (di_or_err.*) |*di| di.deinit(gpa, io) else |_| {};
        module.* = undefined;
    }

    fn getDebugInfo(module: *Module, gpa: Allocator, io: Io) Error!*DebugInfo {
        if (module.di == null) module.di = loadDebugInfo(module, gpa, io);
        return if (module.di.?) |*di| di else |err| err;
    }
    fn loadDebugInfo(module: *const Module, gpa: Allocator, io: Io) Error!DebugInfo {
        const mapped_ptr: [*]const u8 = @ptrCast(module.entry.DllBase);
        const mapped = mapped_ptr[0..module.entry.SizeOfImage];
        var coff_obj = coff.Coff.init(mapped, true) catch return error.InvalidDebugInfo;

        var arena_instance: std.heap.ArenaAllocator = .init(gpa);
        errdefer arena_instance.deinit();
        const arena = arena_instance.allocator();

        // 加载器不会将字符串表映射到内存;因此,若节名位于字符串表中,
        // 就必须从磁盘映射整个映像文件。使用 -gdwarf 生成二进制时可能出现这种情况,
        // 因为节名长度超过 8 字节。
        const mapped_file: ?DebugInfo.MappedFile = mapped: {
            if (!coff_obj.strtabRequired()) break :mapped null;
            var path_buffer: [4 + windows.PATH_MAX_WIDE]u16 = undefined;
            path_buffer[0..4].* = .{ '\\', '?', '?', '\\' }; // openFileAbsoluteW 要求前缀存在。
            const path_slice = module.entry.FullDllName.slice();
            @memcpy(path_buffer[4..][0..path_slice.len], path_slice);
            const coff_file = Io.Threaded.dirOpenFileWtf16(
                null,
                path_buffer[0 .. 4 + path_slice.len],
                .{},
            ) catch |err| switch (err) {
                error.Canceled => |e| return e,
                error.Unexpected => |e| return e,
                error.FileNotFound => return error.MissingDebugInfo,

                error.FileTooBig,
                error.IsDir,
                error.NotDir,
                error.SymLinkLoop,
                error.NameTooLong,
                error.BadPathName,
                => return error.InvalidDebugInfo,

                error.SystemResources,
                error.WouldBlock,
                error.AccessDenied,
                error.PermissionDenied,
                error.NoSpaceLeft,
                error.DeviceBusy,
                error.NoDevice,
                error.PathAlreadyExists,
                error.PipeBusy,
                error.NetworkNotFound,
                error.AntivirusInterference,
                error.ProcessFdQuotaExceeded,
                error.SystemFdQuotaExceeded,
                error.FileLocksUnsupported,
                error.FileBusy,
                error.ReadOnlyFileSystem,
                => return error.ReadFailed,
            };
            errdefer coff_file.close(io);
            var section_handle: windows.HANDLE = undefined;
            const create_section_rc = windows.ntdll.NtCreateSection(
                &section_handle,
                .{
                    .SPECIFIC = .{ .SECTION = .{
                        .QUERY = true,
                        .MAP_READ = true,
                    } },
                    .STANDARD = .{ .RIGHTS = .REQUIRED },
                },
                null,
                null,
                .{ .READONLY = true },
                // 文档称,若未指定 AllocationAttribute,
                // 则默认为 SEC_COMMIT。
                // 实际并非如此,指定 0 会导致 INVALID_PARAMETER_6。
                .{ .COMMIT = true },
                coff_file.handle,
            );
            if (create_section_rc != .SUCCESS) return error.MissingDebugInfo;
            errdefer windows.CloseHandle(section_handle);
            var coff_len: usize = 0;
            var section_view_ptr: ?[*]const u8 = null;
            const process_handle = windows.GetCurrentProcess();
            const map_section_rc = windows.ntdll.NtMapViewOfSection(
                section_handle,
                process_handle,
                @ptrCast(&section_view_ptr),
                null,
                0,
                null,
                &coff_len,
                .Unmap,
                .{},
                .{ .READONLY = true },
            );
            if (map_section_rc != .SUCCESS) return error.MissingDebugInfo;
            errdefer switch (windows.ntdll.NtUnmapViewOfSection(
                process_handle,
                @constCast(section_view_ptr.?),
            )) {
                .SUCCESS => {},
                else => |status| windows.unexpectedStatus(status) catch {},
            };
            const section_view = section_view_ptr.?[0..coff_len];
            coff_obj = coff.Coff.init(section_view, false) catch return error.InvalidDebugInfo;
            break :mapped .{
                .file = coff_file,
                .section_handle = section_handle,
                .section_view = section_view,
            };
        };
        errdefer if (mapped_file) |*mf| mf.deinit(io);

        const coff_image_base = coff_obj.getImageBase();

        var opt_dwarf: ?Dwarf = dwarf: {
            if (coff_obj.getSectionByName(".debug_info") == null) break :dwarf null;

            var sections: Dwarf.SectionArray = undefined;
            inline for (@typeInfo(Dwarf.Section.Id).@"enum".field_names, 0..) |section_name, i| {
                sections[i] = if (coff_obj.getSectionByName("." ++ section_name)) |section_header| .{
                    .data = try coff_obj.getSectionDataAlloc(section_header, arena),
                    .owned = false,
                } else null;
            }
            break :dwarf .{ .sections = sections };
        };
        errdefer if (opt_dwarf) |*dwarf| dwarf.deinit(gpa);

        if (opt_dwarf) |*dwarf| {
            dwarf.open(gpa, native_endian) catch |err| switch (err) {
                error.Overflow,
                error.EndOfStream,
                error.StreamTooLong,
                error.ReadFailed,
                => return error.InvalidDebugInfo,

                error.InvalidDebugInfo,
                error.MissingDebugInfo,
                error.OutOfMemory,
                => |e| return e,
            };
        }

        var opt_pdb: ?Pdb = pdb: {
            const path = coff_obj.getPdbPath() catch {
                return error.InvalidDebugInfo;
            } orelse {
                break :pdb null;
            };
            const pdb_file_open_result = if (fs.path.isAbsolute(path)) res: {
                break :res Io.Dir.cwd().openFile(io, path, .{});
            } else res: {
                const self_dir = std.process.executableDirPathAlloc(io, gpa) catch |err| switch (err) {
                    error.OutOfMemory, error.Unexpected => |e| return e,
                    else => return error.ReadFailed,
                };
                defer gpa.free(self_dir);
                const abs_path = try fs.path.join(gpa, &.{ self_dir, path });
                defer gpa.free(abs_path);
                break :res Io.Dir.cwd().openFile(io, abs_path, .{});
            };
            const pdb_file = pdb_file_open_result catch |err| switch (err) {
                error.FileNotFound, error.IsDir => break :pdb null,
                else => return error.ReadFailed,
            };
            errdefer pdb_file.close(io);

            const pdb_reader = try arena.create(Io.File.Reader);
            pdb_reader.* = pdb_file.reader(io, try arena.alloc(u8, 4096));

            var pdb = Pdb.init(gpa, pdb_reader) catch |err| switch (err) {
                error.OutOfMemory, error.ReadFailed, error.Unexpected => |e| return e,
                else => return error.InvalidDebugInfo,
            };
            errdefer pdb.deinit();
            pdb.parseInfoStream() catch |err| switch (err) {
                error.UnknownPDBVersion => return error.UnsupportedDebugInfo,
                error.EndOfStream => return error.InvalidDebugInfo,

                error.InvalidDebugInfo,
                error.MissingDebugInfo,
                error.OutOfMemory,
                error.ReadFailed,
                => |e| return e,
            };
            pdb.parseDbiStream() catch |err| switch (err) {
                error.UnknownPDBVersion => return error.UnsupportedDebugInfo,

                error.EndOfStream,
                error.EOF,
                error.StreamTooLong,
                error.WriteFailed,
                => return error.InvalidDebugInfo,

                error.InvalidDebugInfo,
                error.OutOfMemory,
                error.ReadFailed,
                => |e| return e,
            };
            pdb.parseIpiStream() catch |err| switch (err) {
                error.UnknownPDBVersion => return error.UnsupportedDebugInfo,

                error.EndOfStream,
                => return error.InvalidDebugInfo,

                error.OutOfMemory,
                error.ReadFailed,
                => |e| return e,
            };

            if (!std.mem.eql(u8, &coff_obj.guid, &pdb.guid) or coff_obj.age != pdb.age)
                return error.InvalidDebugInfo;

            break :pdb pdb;
        };
        errdefer if (opt_pdb) |*pdb| {
            pdb.file_reader.file.close(io);
            pdb.deinit();
        };

        const coff_section_headers: []coff.SectionHeader = if (opt_pdb != null) csh: {
            break :csh try coff_obj.getSectionHeadersAlloc(arena);
        } else &.{};

        return .{
            .arena = arena_instance.state,
            .coff_image_base = coff_image_base,
            .mapped_file = mapped_file,
            .dwarf = opt_dwarf,
            .pdb = opt_pdb,
            .coff_section_headers = coff_section_headers,
        };
    }
};

/// 假定我们已经持有 `si.lock`。
fn findModule(si: *SelfInfo, gpa: Allocator, address: usize) error{ MissingDebugInfo, OutOfMemory, Unexpected }!*Module {
    for (si.modules.items) |*mod| {
        const base = @intFromPtr(mod.entry.DllBase);
        if (address >= base and address < base + mod.entry.SizeOfImage) return mod;
    }
    try si.modules.ensureUnusedCapacity(gpa, 1);
    var entry: *LDR.DATA_TABLE_ENTRY = undefined;
    switch (windows.ntdll.LdrFindEntryForAddress(@ptrFromInt(address), &entry)) {
        .SUCCESS => {},
        .DLL_NOT_FOUND => return error.MissingDebugInfo,
        else => |status| return windows.unexpectedStatus(status),
    }
    if (si.notification_cookie == null) {
        var notification_cookie: LDR.DLL_NOTIFICATION.COOKIE = undefined;
        switch ((try si.getNtdllProc(.LdrRegisterDllNotification))(
            .{},
            &dllNotification,
            si,
            &notification_cookie,
        )) {
            .SUCCESS => si.notification_cookie = notification_cookie,
            else => |status| return windows.unexpectedStatus(status),
        }
    }
    const mod = si.modules.addOneAssumeCapacity();
    mod.* = .{ .entry = entry, .name = null, .di = null };
    return mod;
}

inline fn getNtdllProc(
    si: *SelfInfo,
    comptime proc: std.meta.DeclEnum(windows.ntdll),
) !@TypeOf(&@field(windows.ntdll, @tagName(proc))) {
    return if (load_dll_notification_procs)
        @ptrCast(try si.loadNtdllProc(@tagName(proc)))
    else
        &@field(windows.ntdll, @tagName(proc));
}
fn loadNtdllProc(si: *SelfInfo, name: []const u8) Io.UnexpectedError!*anyopaque {
    const ntdll_handle = si.ntdll_handle orelse ntdll_handle: {
        var ntdll_handle: *anyopaque = undefined;
        switch (windows.ntdll.LdrLoadDll(null, null, &.init(
            &.{ 'n', 't', 'd', 'l', 'l', '.', 'd', 'l', 'l' },
        ), &ntdll_handle)) {
            .SUCCESS => {},
            .DLL_NOT_FOUND => return error.Unexpected,
            else => |status| return windows.unexpectedStatus(status),
        }
        si.ntdll_handle = ntdll_handle;
        break :ntdll_handle ntdll_handle;
    };
    var proc_addr: *anyopaque = undefined;
    switch (windows.ntdll.LdrGetProcedureAddress(ntdll_handle, &.init(name), 0, &proc_addr)) {
        .SUCCESS => {},
        else => |status| return windows.unexpectedStatus(status),
    }
    return proc_addr;
}

fn dllNotification(
    reason: LDR.DLL_NOTIFICATION.REASON,
    data: *const LDR.DLL_NOTIFICATION.DATA,
    context: ?*anyopaque,
) callconv(.winapi) void {
    const si: *SelfInfo = @ptrCast(@alignCast(context));
    switch (reason) {
        .LOADED => {},
        .UNLOADED => {
            const io = std.Options.debug_io;
            si.lock.lockUncancelable(io);
            defer si.lock.unlock(io);
            for (si.modules.items, 0..) |*mod, mod_index| {
                if (mod.entry.DllBase != data.Unloaded.DllBase) continue;
                mod.deinit(std.debug.getDebugInfoAllocator(), io);
                _ = si.modules.swapRemove(mod_index);
                break;
            }
        },
    }
}

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const Dwarf = std.debug.Dwarf;
const Pdb = std.debug.Pdb;
const Error = std.debug.SelfInfoError;
const coff = std.coff;
const fs = std.fs;
const windows = std.os.windows;
const LDR = windows.LDR;

const builtin = @import("builtin");
const native_endian = builtin.target.cpu.arch.endian();
const load_dll_notification_procs = builtin.abi == .msvc and switch (builtin.zig_backend) {
    .stage2_c => true,
    else => switch (builtin.output_mode) {
        .Exe => false,
        .Lib => switch (builtin.link_mode) {
            .static => true,
            .dynamic => false,
        },
        .Obj => true,
    },
};

const SelfInfo = @This();