Skip to content
Standard libraryZig 0.17.0Official documentation
Sourcestd/debug/Dwarf.zig

Source line 1

Implements parsing, decoding, and caching of DWARF information.

This API makes no assumptions about the relationship between the host and the target being debugged. In other words, any DWARF information can be used from any host via this API. Note, however, that the limits of 32-bit addressing can cause very large 64-bit binaries to be impossible to open on 32-bit hosts.

For unopinionated types and bits, see std.dwarf.

Fields

sections: SectionArray = @splat(null)
abbrev_table_list: ArrayList(Abbrev.Table) = .empty

Filled later by the initializer

compile_unit_list: ArrayList(CompileUnit) = .empty

Filled later by the initializer

func_list: ArrayList(Func) = .empty

Filled later by the initializer

ranges: ArrayList(Range) = .empty

Populated by populateRanges.

std.debug.Dwarf.Abbrev

container

Source line 77

Fields

code: u64
tag_id: u64
has_children: bool
attrs: []Attr

std.debug.Dwarf.Abbrev.Attr

container

Source line 88

Fields

id: u64
form_id: u64
payload: i64

Only valid if form_id is .implicit_const

std.debug.Dwarf.Abbrev.deinit

function

Source line 83

fn deinit(abbrev: *Abbrev, gpa: Allocator) void

Parameters

abbrev: *Abbrev
gpa: Allocator

std.debug.Dwarf.Abbrev.Table

container

Source line 95

Fields

offset: u64
abbrevs: []Abbrev

std.debug.Dwarf.Abbrev.Table.deinit

function

Source line 100

fn deinit(table: *Table, gpa: Allocator) void

Parameters

table: *Table
gpa: Allocator

std.debug.Dwarf.Abbrev.Table.get

function

Source line 108

fn get(table: *const Table, abbrev_code: u64) ?*const Abbrev

Parameters

table: *const Table
abbrev_code: u64

std.debug.Dwarf.Allocator

alias

Source line 12

Alias of std.mem.Allocator

std.debug.Dwarf.ArrayList

alias

Source line 23

Alias of std.ArrayList

std.debug.Dwarf.assert

alias

Source line 20

Alias of std.debug.assert

std.debug.Dwarf.AT

alias

Source line 15

Alias of std.dwarf.AT

std.debug.Dwarf.bad

type-function

Source line 1615

This function is to make it handy to comment out the return and make it into a crash when working on this file.

pub fn bad() error{InvalidDebugInfo}

Errors

InvalidDebugInfo

std.debug.Dwarf.cast

alias

Source line 21

Alias of std.math.cast

std.debug.Dwarf.compactUnwindToDwarfRegNumber

function

Source line 1503

Returns the DWARF register number for an x86_64 register number found in compact unwind info

pub fn compactUnwindToDwarfRegNumber(unwind_reg_number: u3) !u16

Parameters

unwind_reg_number: u3

std.debug.Dwarf.CompileUnit

container

Source line 116

Fields

offset: u64
size: u64
version: u16
format: Format
addr_size_bytes: u8
abbrev_offset: u64
die: Die
pc_range: ?PcRange
str_offsets_base: usize
addr_base: usize
rnglists_base: usize
loclists_base: usize
frame_base: ?*const FormValue
src_loc_cache: ?SrcLocCache

std.debug.Dwarf.CompileUnit.SrcLocCache

container

Source line 133

Fields

line_table: LineTable
directories: []const FileEntry
files: []FileEntry
version: u16

std.debug.Dwarf.CompileUnit.SrcLocCache.findSource

function

Source line 158

pub fn findSource(slc: *const SrcLocCache, address: u64) !LineEntry

Parameters

slc: *const SrcLocCache
address: u64

std.debug.Dwarf.CompileUnit.SrcLocCache.findSource.order

function

Source line 160

fn order(context: u64, item: u64) std.math.Order

Parameters

context: u64
item: u64

std.debug.Dwarf.CompileUnit.SrcLocCache.LineEntry

container

Source line 141

Fields

line: u32
column: u32
file: u32

Offset by 1 depending on whether Dwarf version is >= 5.

std.debug.Dwarf.CompileUnit.SrcLocCache.LineEntry.invalid

constant

Source line 147

LineEntry

std.debug.Dwarf.CompileUnit.SrcLocCache.LineEntry.isInvalid

function

Source line 153

pub fn isInvalid(le: LineEntry) bool

Parameters

le: LineEntry

std.debug.Dwarf.CompileUnit.SrcLocCache.LineTable

type

Source line 139

std.debug.Dwarf.debug_debug_mode

primitive

Source line 36

Useful to temporarily enable while working on this file.

std.debug.Dwarf.DebugRangeIterator

container

Source line 700

Fields

base_address: u64
section_type: Section.Id
di: *const Dwarf
endian: Endian
compile_unit: *const CompileUnit
fr: Reader

std.debug.Dwarf.DebugRangeIterator.init

function

Source line 708

pub fn init(ranges_value: *const FormValue, di: *const Dwarf, endian: Endian, compile_unit: *const CompileUnit) !@This()

Parameters

ranges_value: *const FormValue
di: *const Dwarf
endian: Endian
compile_unit: *const CompileUnit

std.debug.Dwarf.DebugRangeIterator.next

function

Source line 756

pub fn next(self: *@This()) !?PcRange

Parameters

self: *@This()

std.debug.Dwarf.deinit

function

Source line 323

pub fn deinit(di: *Dwarf, gpa: Allocator) void

Parameters

di: *Dwarf
gpa: Allocator

std.debug.Dwarf.Die

container

Source line 209

Fields

tag_id: u64
has_children: bool
attrs: []Attr

std.debug.Dwarf.Die.Attr

container

Source line 214

Fields

id: u64
value: FormValue

std.debug.Dwarf.Die.deinit

function

Source line 219

fn deinit(self: *Die, gpa: Allocator) void

Parameters

self: *Die
gpa: Allocator

std.debug.Dwarf.Die.getAttr

function

Source line 224

fn getAttr(self: *const Die, id: u64) ?*const FormValue

Parameters

self: *const Die
id: u64

std.debug.Dwarf.Die.getAttrAddr

function

Source line 231

fn getAttrAddr( self: *const Die, di: *const Dwarf, endian: Endian, id: u64, compile_unit: *const CompileUnit, ) error{ InvalidDebugInfo, MissingDebugInfo }!u64

Parameters

self: *const Die
di: *const Dwarf
endian: Endian
id: u64
compile_unit: *const CompileUnit

Errors

InvalidDebugInfo
MissingDebugInfo

std.debug.Dwarf.Die.getAttrRef

function

Source line 251

fn getAttrRef(self: *const Die, id: u64, unit_offset: u64, unit_len: u64) !u64

Parameters

self: *const Die
id: u64
unit_offset: u64
unit_len: u64

std.debug.Dwarf.Die.getAttrSecOffset

function

Source line 246

fn getAttrSecOffset(self: *const Die, id: u64) !u64

Parameters

self: *const Die
id: u64

std.debug.Dwarf.Die.getAttrString

function

Source line 260

pub fn getAttrString( self: *const Die, di: *Dwarf, endian: Endian, id: u64, opt_str: ?[]const u8, compile_unit: *const CompileUnit, ) error{ InvalidDebugInfo, MissingDebugInfo }![]const u8

Parameters

self: *const Die
di: *Dwarf
endian: Endian
id: u64
opt_str: ?[]const u8
compile_unit: *const CompileUnit

Errors

InvalidDebugInfo
MissingDebugInfo

std.debug.Dwarf.DW

alias

Source line 14

Alias of std.dwarf

std.debug.Dwarf.Dwarf

alias

Source line 29

Alias of std.debug.Dwarf

std.debug.Dwarf.Endian

alias

Source line 24

Alias of std.lang.Endian

std.debug.Dwarf.Error

alias

Source line 27

Alias of std.debug.SelfInfoError

std.debug.Dwarf.expression

alias

Source line 31

Alias of std.debug.Dwarf.expression

std.debug.Dwarf.FileEntry

container

Source line 1424

Fields

path: []const u8
dir_index: u32 = 0
mtime: u64 = 0
size: u64 = 0
md5: [16]u8 = @splat(0)

std.debug.Dwarf.findCompileUnit

function

Source line 852

TODO: change this to binary searching the sorted compile unit list

pub fn findCompileUnit(di: *const Dwarf, endian: Endian, target_address: u64) !*CompileUnit

Parameters

di: *const Dwarf
endian: Endian
target_address: u64

std.debug.Dwarf.FORM

alias

Source line 16

Alias of std.dwarf.FORM

std.debug.Dwarf.Format

alias

Source line 17

Alias of std.dwarf.Format

std.debug.Dwarf.FormValue

container

Source line 170

Fields

addr: u64
addrx: u64
block: []const u8
udata: u64
data16: *const [16]u8
sdata: i64
exprloc: []const u8
flag: bool
sec_offset: u64
ref: u64
ref_addr: u64
string: [:0]const u8
strp: u64
strx: u64
line_strp: u64
loclistx: u64
rnglistx: u64

std.debug.Dwarf.FormValue.getString

function

Source line 189

fn getString(fv: FormValue, di: Dwarf) ![:0]const u8

Parameters

fv: FormValue
di: Dwarf

std.debug.Dwarf.FormValue.getUInt

function

Source line 198

fn getUInt(fv: FormValue, comptime U: type) !U

Parameters

fv: FormValue
U: type

std.debug.Dwarf.fpRegNum

function

Source line 1542

pub fn fpRegNum(arch: std.Target.Cpu.Arch) u16

Parameters

arch: std.Target.Cpu.Arch

std.debug.Dwarf.Func

container

Source line 314

Fields

pc_range: ?PcRange
name: ?[]const u8

std.debug.Dwarf.getAbbrevTable

function

Source line 870

Gets an already existing AbbrevTable given the abbrev_offset, or if not found, seeks in the stream and parses it.

fn getAbbrevTable(di: *Dwarf, gpa: Allocator, abbrev_offset: u64) !*const Abbrev.Table

Parameters

di: *Dwarf
gpa: Allocator
abbrev_offset: u64

std.debug.Dwarf.getLineNumberInfo

function

Source line 1297

pub fn getLineNumberInfo( d: *Dwarf, gpa: Allocator, text_arena: Allocator, endian: Endian, compile_unit: *CompileUnit, target_address: u64, ) !std.debug.SourceLocation

Parameters

d: *Dwarf
gpa: Allocator
text_arena: Allocator
endian: Endian
compile_unit: *CompileUnit
target_address: u64

std.debug.Dwarf.getLineString

function

Source line 1325

fn getLineString(di: Dwarf, offset: u64) ![:0]const u8

Parameters

di: Dwarf
offset: u64

std.debug.Dwarf.getString

function

Source line 1321

fn getString(di: Dwarf, offset: u64) ![:0]const u8

Parameters

di: Dwarf
offset: u64

std.debug.Dwarf.getStringGeneric

function

Source line 1629

fn getStringGeneric(opt_str: ?[]const u8, offset: u64) ![:0]const u8

Parameters

opt_str: ?[]const u8
offset: u64

std.debug.Dwarf.getSymbolName

function

Source line 345

pub fn getSymbolName(di: *const Dwarf, address: u64) ?[]const u8

Parameters

di: *const Dwarf
address: u64

std.debug.Dwarf.getSymbols

function

Source line 1638

pub fn getSymbols( di: *Dwarf, symbol_allocator: Allocator, text_arena: Allocator, endian: Endian, address: u64, resolve_inline_callers: bool, symbols: *std.ArrayList(std.debug.Symbol), ) std.debug.SelfInfoError!void

Parameters

di: *Dwarf
symbol_allocator: Allocator
text_arena: Allocator
endian: Endian
address: u64
resolve_inline_callers: bool
symbols: *std.ArrayList(std.debug.Symbol)

Errors

Canceled
InvalidDebugInfo

The required debug info is invalid or corrupted.

MissingDebugInfo

The required debug info could not be found.

OutOfMemory
ReadFailed

The required debug info could not be read from disk due to some IO error.

Unexpected
UnsupportedDebugInfo

The required debug info was found, and may be valid, but is not supported by this implementation.

std.debug.Dwarf.invalidDebugInfoDetected

function

Source line 1620

pub fn invalidDebugInfoDetected() void

std.debug.Dwarf.Io

alias

Source line 25

Alias of std.Io

std.debug.Dwarf.ipRegNum

function

Source line 1516

Returns null for CPU architectures without an instruction pointer register.

pub fn ipRegNum(arch: std.Target.Cpu.Arch) ?u16

Parameters

arch: std.Target.Cpu.Arch

std.debug.Dwarf.LineNumberProgram

container

Source line 1432

Fields

address: u64
file: usize
line: i64
column: u64
version: u16
is_stmt: bool
basic_block: bool
default_is_stmt: bool

std.debug.Dwarf.LineNumberProgram.addRow

function

Source line 1466

pub fn addRow(prog: *LineNumberProgram, gpa: Allocator, table: *CompileUnit.SrcLocCache.LineTable) !void

Parameters

std.debug.Dwarf.LineNumberProgram.init

function

Source line 1453

pub fn init(is_stmt: bool, version: u16) LineNumberProgram

Parameters

is_stmt: bool
version: u16

std.debug.Dwarf.LineNumberProgram.reset

function

Source line 1444

pub fn reset(self: *LineNumberProgram) void

Parameters

std.debug.Dwarf.maxInt

alias

Source line 22

Alias of std.math.maxInt

std.debug.Dwarf.mem

alias

Source line 13

Alias of std.mem

std.debug.Dwarf.missing

type-function

Source line 1624

pub fn missing() error{MissingDebugInfo}

Errors

MissingDebugInfo

std.debug.Dwarf.num_sections

constant

Source line 296

std.debug.Dwarf.open

function

Source line 304

Initialize DWARF info. The caller has the responsibility to initialize most the Dwarf fields before calling. binary_mem is the raw bytes of the main binary file (not the secondary debug info file).

pub fn open(d: *Dwarf, gpa: Allocator, endian: Endian) OpenError!void

Parameters

d: *Dwarf
gpa: Allocator
endian: Endian

Errors

EndOfStream ScanError
InvalidDebugInfo ScanError
MissingDebugInfo ScanError
OutOfMemory Error
Overflow ScanError
ReadFailed ScanError
StreamTooLong ScanError

std.debug.Dwarf.OpenError

alias

Source line 299

Alias of std.debug.Dwarf.ScanError

std.debug.Dwarf.parseAbbrevTable

function

Source line 883

fn parseAbbrevTable(di: *Dwarf, gpa: Allocator, offset: u64) !Abbrev.Table

Parameters

di: *Dwarf
gpa: Allocator
offset: u64

std.debug.Dwarf.parseDie

function

Source line 932

fn parseDie( fr: *Reader, attrs_buf: []Die.Attr, abbrev_table: *const Abbrev.Table, format: Format, endian: Endian, addr_size_bytes: u8, version: u16, ) ScanError!?Die

Parameters

fr: *Reader
attrs_buf: []Die.Attr
abbrev_table: *const Abbrev.Table
format: Format
endian: Endian
addr_size_bytes: u8
version: u16

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.parseFormValue

function

Source line 1355

fn parseFormValue( r: *Reader, form_id: u64, format: Format, endian: Endian, addr_size_bytes: u8, implicit_const: ?i64, version: u16, ) ScanError!FormValue

Parameters

r: *Reader
form_id: u64
format: Format
endian: Endian
addr_size_bytes: u8
implicit_const: ?i64
version: u16

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.PcRange

container

Source line 309

Fields

start: u64
end: u64

std.debug.Dwarf.populateRanges

function

Source line 666

pub fn populateRanges(d: *Dwarf, gpa: Allocator, endian: Endian) ScanError!void

Parameters

d: *Dwarf
gpa: Allocator
endian: Endian

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.populateRanges.lessThan

function

Source line 693

pub fn lessThan(ctx: void, a: Range, b: Range) bool

Parameters

ctx: void
a: Range
b: Range

std.debug.Dwarf.populateSrcLocCache

function

Source line 1292

pub fn populateSrcLocCache(d: *Dwarf, gpa: Allocator, endian: Endian, cu: *CompileUnit) ScanError!void

Parameters

d: *Dwarf
gpa: Allocator
endian: Endian
cu: *CompileUnit

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.Range

container

Source line 50

Fields

start: u64
end: u64
compile_unit_index: usize

Index into compile_unit_list.

std.debug.Dwarf.readAddress

function

Source line 1685

fn readAddress(r: *Reader, endian: Endian, addr_size_bytes: u8) !u64

Parameters

r: *Reader
endian: Endian
addr_size_bytes: u8

std.debug.Dwarf.readDebugAddr

function

Source line 1329

fn readDebugAddr(di: Dwarf, endian: Endian, compile_unit: *const CompileUnit, index: u64) !u64

Parameters

di: Dwarf
endian: Endian
compile_unit: *const CompileUnit
index: u64

std.debug.Dwarf.Reader

alias

Source line 26

Alias of std.Io.Reader

std.debug.Dwarf.readFormatSizedInt

function

Source line 1678

DWARF5 7.4: "In the 32-bit DWARF format, all values that represent lengths of DWARF sections and offsets relative to the beginning of DWARF sections are represented using four bytes. In the 64-bit DWARF format, all values that represent lengths of DWARF sections and offsets relative to the beginning of DWARF sections are represented using eight bytes".

This function is for reading such values.

fn readFormatSizedInt(r: *Reader, format: std.dwarf.Format, endian: Endian) !u64

Parameters

r: *Reader
format: std.dwarf.Format
endian: Endian

std.debug.Dwarf.readUnitHeader

function

Source line 1486

pub fn readUnitHeader(r: *Reader, endian: Endian) ScanError!UnitHeader

Parameters

r: *Reader
endian: Endian

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.RLE

alias

Source line 18

Alias of std.dwarf.RLE

std.debug.Dwarf.runLineNumberProgram

function

Source line 958

Ensures that addresses in the returned LineTable are monotonically increasing.

fn runLineNumberProgram(d: *Dwarf, gpa: Allocator, endian: Endian, compile_unit: *const CompileUnit) !CompileUnit.SrcLocCache

Parameters

d: *Dwarf
gpa: Allocator
endian: Endian
compile_unit: *const CompileUnit

std.debug.Dwarf.runLineNumberProgram.lessThan

function

Source line 1276

pub fn lessThan(ctx: @This(), a_index: usize, b_index: usize) bool

Parameters

ctx: @This()
a_index: usize
b_index: usize

std.debug.Dwarf.scanAllCompileUnits

function

Source line 570

fn scanAllCompileUnits(di: *Dwarf, gpa: Allocator, endian: Endian) ScanError!void

Parameters

di: *Dwarf
gpa: Allocator
endian: Endian

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.scanAllFunctions

function

Source line 372

fn scanAllFunctions(di: *Dwarf, gpa: Allocator, endian: Endian) ScanError!void

Parameters

di: *Dwarf
gpa: Allocator
endian: Endian

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.ScanError

error-set

Source line 363

Errors

EndOfStream
InvalidDebugInfo
MissingDebugInfo
OutOfMemory Error
Overflow
ReadFailed
StreamTooLong

std.debug.Dwarf.section

function

Source line 319

pub fn section(di: Dwarf, dwarf_section: Section.Id) ?[]const u8

Parameters

di: Dwarf
dwarf_section: Section.Id

std.debug.Dwarf.Section

container

Source line 57

Fields

data: []const u8
owned: bool

If data is owned by this Dwarf.

std.debug.Dwarf.Section.Id

container

Source line 62

Fields

debug_info
debug_abbrev
debug_str
debug_str_offsets
debug_line
debug_line_str
debug_ranges
debug_loclists
debug_rnglists
debug_addr
debug_names

std.debug.Dwarf.SectionArray

type

Source line 297

std.debug.Dwarf.SelfUnwinder

alias

Source line 33

Alias of std.debug.Dwarf.SelfUnwinder

std.debug.Dwarf.spRegNum

function

Source line 1568

pub fn spRegNum(arch: std.Target.Cpu.Arch) u16

Parameters

arch: std.Target.Cpu.Arch

std.debug.Dwarf.std

alias

Source line 11

Alias of std

std.debug.Dwarf.supportsUnwinding

function

Source line 1598

Tells whether unwinding for this target is supported by the Dwarf standard.

See also std.debug.SelfInfo.can_unwind which tells whether the Zig standard library has a working implementation of unwinding for the current target.

pub fn supportsUnwinding(target: *const std.Target) bool

Parameters

target: *const std.Target

std.debug.Dwarf.UnitHeader

container

Source line 1480

Fields

format: Format
header_length: u4
unit_length: u64

std.debug.Dwarf.Unwind

alias

Source line 32

Alias of std.debug.Dwarf.Unwind

std.debug.Dwarf.UT

alias

Source line 19

Alias of std.dwarf.UT

Source code

std/debug/Dwarf.zig

//! Implements parsing, decoding, and caching of DWARF information.
//!
//! This API makes no assumptions about the relationship between the host and
//! the target being debugged. In other words, any DWARF information can be used
//! from any host via this API. Note, however, that the limits of 32-bit
//! addressing can cause very large 64-bit binaries to be impossible to open on
//! 32-bit hosts.
//!
//! For unopinionated types and bits, see `std.dwarf`.

const std = @import("../std.zig");
const Allocator = std.mem.Allocator;
const mem = std.mem;
const DW = std.dwarf;
const AT = DW.AT;
const FORM = DW.FORM;
const Format = DW.Format;
const RLE = DW.RLE;
const UT = DW.UT;
const assert = std.debug.assert;
const cast = std.math.cast;
const maxInt = std.math.maxInt;
const ArrayList = std.ArrayList;
const Endian = std.builtin.Endian;
const Io = std.Io;
const Reader = Io.Reader;
const Error = std.debug.SelfInfoError;

const Dwarf = @This();

pub const expression = @import("Dwarf/expression.zig");
pub const Unwind = @import("Dwarf/Unwind.zig");
pub const SelfUnwinder = @import("Dwarf/SelfUnwinder.zig");

/// Useful to temporarily enable while working on this file.
const debug_debug_mode = false;

sections: SectionArray = @splat(null),

/// Filled later by the initializer
abbrev_table_list: ArrayList(Abbrev.Table) = .empty,
/// Filled later by the initializer
compile_unit_list: ArrayList(CompileUnit) = .empty,
/// Filled later by the initializer
func_list: ArrayList(Func) = .empty,

/// Populated by `populateRanges`.
ranges: ArrayList(Range) = .empty,

pub const Range = struct {
    start: u64,
    end: u64,
    /// Index into `compile_unit_list`.
    compile_unit_index: usize,
};

pub const Section = struct {
    data: []const u8,
    /// If `data` is owned by this Dwarf.
    owned: bool,

    pub const Id = enum {
        debug_info,
        debug_abbrev,
        debug_str,
        debug_str_offsets,
        debug_line,
        debug_line_str,
        debug_ranges,
        debug_loclists,
        debug_rnglists,
        debug_addr,
        debug_names,
    };
};

pub const Abbrev = struct {
    code: u64,
    tag_id: u64,
    has_children: bool,
    attrs: []Attr,

    fn deinit(abbrev: *Abbrev, gpa: Allocator) void {
        gpa.free(abbrev.attrs);
        abbrev.* = undefined;
    }

    const Attr = struct {
        id: u64,
        form_id: u64,
        /// Only valid if form_id is .implicit_const
        payload: i64,
    };

    const Table = struct {
        // offset from .debug_abbrev
        offset: u64,
        abbrevs: []Abbrev,

        fn deinit(table: *Table, gpa: Allocator) void {
            for (table.abbrevs) |*abbrev| {
                abbrev.deinit(gpa);
            }
            gpa.free(table.abbrevs);
            table.* = undefined;
        }

        fn get(table: *const Table, abbrev_code: u64) ?*const Abbrev {
            return for (table.abbrevs) |*abbrev| {
                if (abbrev.code == abbrev_code) break abbrev;
            } else null;
        }
    };
};

pub const CompileUnit = struct {
    offset: u64,
    size: u64,
    version: u16,
    format: Format,
    addr_size_bytes: u8,
    abbrev_offset: u64,
    die: Die,
    pc_range: ?PcRange,
    str_offsets_base: usize,
    addr_base: usize,
    rnglists_base: usize,
    loclists_base: usize,
    frame_base: ?*const FormValue,

    src_loc_cache: ?SrcLocCache,

    pub const SrcLocCache = struct {
        line_table: LineTable,
        directories: []const FileEntry,
        files: []FileEntry,
        version: u16,

        pub const LineTable = std.array_hash_map.Auto(u64, LineEntry);

        pub const LineEntry = struct {
            line: u32,
            column: u32,
            /// Offset by 1 depending on whether Dwarf version is >= 5.
            file: u32,

            pub const invalid: LineEntry = .{
                .line = undefined,
                .column = undefined,
                .file = std.math.maxInt(u32),
            };

            pub fn isInvalid(le: LineEntry) bool {
                return le.file == invalid.file;
            }
        };

        pub fn findSource(slc: *const SrcLocCache, address: u64) !LineEntry {
            const index = std.sort.upperBound(u64, slc.line_table.keys(), address, struct {
                fn order(context: u64, item: u64) std.math.Order {
                    return std.math.order(context, item);
                }
            }.order);
            if (index == 0) return missing();
            return slc.line_table.values()[index - 1];
        }
    };
};

pub const FormValue = union(enum) {
    addr: u64,
    addrx: u64,
    block: []const u8,
    udata: u64,
    data16: *const [16]u8,
    sdata: i64,
    exprloc: []const u8,
    flag: bool,
    sec_offset: u64,
    ref: u64,
    ref_addr: u64,
    string: [:0]const u8,
    strp: u64,
    strx: u64,
    line_strp: u64,
    loclistx: u64,
    rnglistx: u64,

    fn getString(fv: FormValue, di: Dwarf) ![:0]const u8 {
        switch (fv) {
            .string => |s| return s,
            .strp => |off| return di.getString(off),
            .line_strp => |off| return di.getLineString(off),
            else => return bad(),
        }
    }

    fn getUInt(fv: FormValue, comptime U: type) !U {
        return switch (fv) {
            inline .udata,
            .sdata,
            .sec_offset,
            => |c| cast(U, c) orelse bad(),
            else => bad(),
        };
    }
};

pub const Die = struct {
    tag_id: u64,
    has_children: bool,
    attrs: []Attr,

    const Attr = struct {
        id: u64,
        value: FormValue,
    };

    fn deinit(self: *Die, gpa: Allocator) void {
        gpa.free(self.attrs);
        self.* = undefined;
    }

    fn getAttr(self: *const Die, id: u64) ?*const FormValue {
        for (self.attrs) |*attr| {
            if (attr.id == id) return &attr.value;
        }
        return null;
    }

    fn getAttrAddr(
        self: *const Die,
        di: *const Dwarf,
        endian: Endian,
        id: u64,
        compile_unit: *const CompileUnit,
    ) error{ InvalidDebugInfo, MissingDebugInfo }!u64 {
        const form_value = self.getAttr(id) orelse return error.MissingDebugInfo;
        return switch (form_value.*) {
            .addr => |value| value,
            .addrx => |index| di.readDebugAddr(endian, compile_unit, index),
            else => bad(),
        };
    }

    fn getAttrSecOffset(self: *const Die, id: u64) !u64 {
        const form_value = self.getAttr(id) orelse return error.MissingDebugInfo;
        return form_value.getUInt(u64);
    }

    fn getAttrRef(self: *const Die, id: u64, unit_offset: u64, unit_len: u64) !u64 {
        const form_value = self.getAttr(id) orelse return error.MissingDebugInfo;
        return switch (form_value.*) {
            .ref => |offset| if (offset < unit_len) unit_offset + offset else bad(),
            .ref_addr => |addr| addr,
            else => bad(),
        };
    }

    pub fn getAttrString(
        self: *const Die,
        di: *Dwarf,
        endian: Endian,
        id: u64,
        opt_str: ?[]const u8,
        compile_unit: *const CompileUnit,
    ) error{ InvalidDebugInfo, MissingDebugInfo }![]const u8 {
        const form_value = self.getAttr(id) orelse return error.MissingDebugInfo;
        switch (form_value.*) {
            .string => |value| return value,
            .strp => |offset| return di.getString(offset),
            .strx => |index| {
                const debug_str_offsets = di.section(.debug_str_offsets) orelse return bad();
                if (compile_unit.str_offsets_base == 0) return bad();
                switch (compile_unit.format) {
                    .@"32" => {
                        const byte_offset = compile_unit.str_offsets_base + 4 * index;
                        if (byte_offset + 4 > debug_str_offsets.len) return bad();
                        const offset = mem.readInt(u32, debug_str_offsets[@intCast(byte_offset)..][0..4], endian);
                        return getStringGeneric(opt_str, offset);
                    },
                    .@"64" => {
                        const byte_offset = compile_unit.str_offsets_base + 8 * index;
                        if (byte_offset + 8 > debug_str_offsets.len) return bad();
                        const offset = mem.readInt(u64, debug_str_offsets[@intCast(byte_offset)..][0..8], endian);
                        return getStringGeneric(opt_str, offset);
                    },
                }
            },
            .line_strp => |offset| return di.getLineString(offset),
            else => return bad(),
        }
    }
};

const num_sections = std.enums.directEnumArrayLen(Section.Id, 0);
pub const SectionArray = [num_sections]?Section;

pub const OpenError = ScanError;

/// Initialize DWARF info. The caller has the responsibility to initialize most
/// the `Dwarf` fields before calling. `binary_mem` is the raw bytes of the
/// main binary file (not the secondary debug info file).
pub fn open(d: *Dwarf, gpa: Allocator, endian: Endian) OpenError!void {
    try d.scanAllFunctions(gpa, endian);
    try d.scanAllCompileUnits(gpa, endian);
}

const PcRange = struct {
    start: u64,
    end: u64,
};

const Func = struct {
    pc_range: ?PcRange,
    name: ?[]const u8,
};

pub fn section(di: Dwarf, dwarf_section: Section.Id) ?[]const u8 {
    return if (di.sections[@backingInt(dwarf_section)]) |s| s.data else null;
}

pub fn deinit(di: *Dwarf, gpa: Allocator) void {
    for (di.sections) |opt_section| {
        if (opt_section) |s| if (s.owned) gpa.free(s.data);
    }
    for (di.abbrev_table_list.items) |*abbrev| {
        abbrev.deinit(gpa);
    }
    di.abbrev_table_list.deinit(gpa);
    for (di.compile_unit_list.items) |*cu| {
        if (cu.src_loc_cache) |*slc| {
            slc.line_table.deinit(gpa);
            gpa.free(slc.directories);
            gpa.free(slc.files);
        }
        cu.die.deinit(gpa);
    }
    di.compile_unit_list.deinit(gpa);
    di.func_list.deinit(gpa);
    di.ranges.deinit(gpa);
    di.* = undefined;
}

pub fn getSymbolName(di: *const Dwarf, address: u64) ?[]const u8 {
    // Iterate the function list backwards so that we see child DIEs before their parents. This is
    // important because `DW_TAG_inlined_subroutine` DIEs will have a range which is a sub-range of
    // their caller, and we want to return the callee's name, not the caller's.
    var i: usize = di.func_list.items.len;
    while (i > 0) {
        i -= 1;
        const func = &di.func_list.items[i];
        if (func.pc_range) |range| {
            if (address >= range.start and address < range.end) {
                return func.name;
            }
        }
    }

    return null;
}

pub const ScanError = error{
    InvalidDebugInfo,
    MissingDebugInfo,
    ReadFailed,
    EndOfStream,
    Overflow,
    StreamTooLong,
} || Allocator.Error;

fn scanAllFunctions(di: *Dwarf, gpa: Allocator, endian: Endian) ScanError!void {
    var fr: Reader = .fixed(di.section(.debug_info).?);
    var this_unit_offset: u64 = 0;

    while (this_unit_offset < fr.buffer.len) {
        fr.seek = @intCast(this_unit_offset);

        const unit_header = try readUnitHeader(&fr, endian);
        if (unit_header.unit_length == 0) return;
        const next_offset = unit_header.header_length + unit_header.unit_length;

        const version = try fr.takeInt(u16, endian);
        var address_size: u8 = undefined;
        var debug_abbrev_offset: u64 = undefined;
        if (version == 5) {
            const unit_type = try fr.takeByte();
            if (unit_type != DW.UT.compile) return bad();
            address_size = try fr.takeByte();
            debug_abbrev_offset = try readFormatSizedInt(&fr, unit_header.format, endian);
        } else if (version >= 2 and version < 5) {
            debug_abbrev_offset = try readFormatSizedInt(&fr, unit_header.format, endian);
            address_size = try fr.takeByte();
        } else {
            this_unit_offset += next_offset;
            continue;
        }

        const abbrev_table = try di.getAbbrevTable(gpa, debug_abbrev_offset);

        var max_attrs: usize = 0;
        var zig_padding_abbrev_code: u7 = 0;
        for (abbrev_table.abbrevs) |abbrev| {
            max_attrs = @max(max_attrs, abbrev.attrs.len);
            if (cast(u7, abbrev.code)) |code| {
                if (abbrev.tag_id == DW.TAG.ZIG_padding and
                    !abbrev.has_children and
                    abbrev.attrs.len == 0)
                {
                    zig_padding_abbrev_code = code;
                }
            }
        }
        const attrs_buf = try gpa.alloc(Die.Attr, max_attrs * 3);
        defer gpa.free(attrs_buf);
        var attrs_bufs: [3][]Die.Attr = undefined;
        for (&attrs_bufs, 0..) |*buf, index| buf.* = attrs_buf[index * max_attrs ..][0..max_attrs];

        const next_unit_pos = this_unit_offset + next_offset;

        var compile_unit: CompileUnit = .{
            .offset = this_unit_offset,
            .size = next_offset,
            .version = version,
            .format = unit_header.format,
            .addr_size_bytes = address_size,
            .abbrev_offset = debug_abbrev_offset,
            .die = undefined,
            .pc_range = null,
            .str_offsets_base = 0,
            .addr_base = 0,
            .rnglists_base = 0,
            .loclists_base = 0,
            .frame_base = null,
            .src_loc_cache = null,
        };

        while (true) {
            fr.seek = std.mem.findNonePos(u8, fr.buffer, fr.seek, &.{
                zig_padding_abbrev_code, 0,
            }) orelse fr.buffer.len;
            if (fr.seek >= next_unit_pos) break;
            var die_obj = (try parseDie(
                &fr,
                attrs_bufs[0],
                abbrev_table,
                unit_header.format,
                endian,
                address_size,
                version,
            )) orelse continue;

            switch (die_obj.tag_id) {
                DW.TAG.compile_unit => {
                    compile_unit.die = die_obj;
                    compile_unit.die.attrs = attrs_bufs[1][0..die_obj.attrs.len];
                    @memcpy(compile_unit.die.attrs, die_obj.attrs);

                    compile_unit.str_offsets_base = if (die_obj.getAttr(AT.str_offsets_base)) |fv| try fv.getUInt(usize) else 0;
                    compile_unit.addr_base = if (die_obj.getAttr(AT.addr_base)) |fv| try fv.getUInt(usize) else 0;
                    compile_unit.rnglists_base = if (die_obj.getAttr(AT.rnglists_base)) |fv| try fv.getUInt(usize) else 0;
                    compile_unit.loclists_base = if (die_obj.getAttr(AT.loclists_base)) |fv| try fv.getUInt(usize) else 0;
                    compile_unit.frame_base = die_obj.getAttr(AT.frame_base);
                },
                DW.TAG.subprogram, DW.TAG.inlined_subroutine, DW.TAG.subroutine, DW.TAG.entry_point => {
                    const fn_name = x: {
                        var this_die_obj = die_obj;
                        // Prevent endless loops
                        for (0..3) |_| {
                            if (this_die_obj.getAttr(AT.name)) |_| {
                                break :x try this_die_obj.getAttrString(di, endian, AT.name, di.section(.debug_str), &compile_unit);
                            } else if (this_die_obj.getAttr(AT.abstract_origin)) |_| {
                                const after_die_offset = fr.seek;
                                defer fr.seek = after_die_offset;

                                // Follow the DIE it points to and repeat
                                const ref_offset = try this_die_obj.getAttrRef(AT.abstract_origin, this_unit_offset, next_offset);
                                fr.seek = @intCast(ref_offset);
                                this_die_obj = (try parseDie(
                                    &fr,
                                    attrs_bufs[2],
                                    abbrev_table, // wrong abbrev table for different cu
                                    unit_header.format,
                                    endian,
                                    address_size,
                                    version,
                                )) orelse return bad();
                            } else if (this_die_obj.getAttr(AT.specification)) |_| {
                                const after_die_offset = fr.seek;
                                defer fr.seek = after_die_offset;

                                // Follow the DIE it points to and repeat
                                const ref_offset = try this_die_obj.getAttrRef(AT.specification, this_unit_offset, next_offset);
                                fr.seek = @intCast(ref_offset);
                                this_die_obj = (try parseDie(
                                    &fr,
                                    attrs_bufs[2],
                                    abbrev_table, // wrong abbrev table for different cu
                                    unit_header.format,
                                    endian,
                                    address_size,
                                    version,
                                )) orelse return bad();
                            } else {
                                break :x null;
                            }
                        }

                        break :x null;
                    };

                    var range_added = if (die_obj.getAttrAddr(di, endian, AT.low_pc, &compile_unit)) |low_pc| blk: {
                        if (die_obj.getAttr(AT.high_pc)) |high_pc_value| {
                            const pc_end = switch (high_pc_value.*) {
                                .addr => |value| value,
                                .udata => |offset| low_pc + offset,
                                else => return bad(),
                            };

                            try di.func_list.append(gpa, .{
                                .name = fn_name,
                                .pc_range = .{
                                    .start = low_pc,
                                    .end = pc_end,
                                },
                            });

                            break :blk true;
                        }

                        break :blk false;
                    } else |err| blk: {
                        if (err != error.MissingDebugInfo) return err;
                        break :blk false;
                    };

                    if (die_obj.getAttr(AT.ranges)) |ranges_value| blk: {
                        var iter = DebugRangeIterator.init(ranges_value, di, endian, &compile_unit) catch |err| {
                            if (err != error.MissingDebugInfo) return err;
                            break :blk;
                        };

                        while (try iter.next()) |range| {
                            range_added = true;
                            try di.func_list.append(gpa, .{
                                .name = fn_name,
                                .pc_range = .{
                                    .start = range.start,
                                    .end = range.end,
                                },
                            });
                        }
                    }

                    if (fn_name != null and !range_added) {
                        try di.func_list.append(gpa, .{
                            .name = fn_name,
                            .pc_range = null,
                        });
                    }
                },
                else => {},
            }
        }

        this_unit_offset += next_offset;
    }
}

fn scanAllCompileUnits(di: *Dwarf, gpa: Allocator, endian: Endian) ScanError!void {
    var fr: Reader = .fixed(di.section(.debug_info).?);
    var this_unit_offset: u64 = 0;

    var attrs_buf = std.array_list.Managed(Die.Attr).init(gpa);
    defer attrs_buf.deinit();

    while (this_unit_offset < fr.buffer.len) {
        fr.seek = @intCast(this_unit_offset);

        const unit_header = try readUnitHeader(&fr, endian);
        if (unit_header.unit_length == 0) return;
        const next_offset = unit_header.header_length + unit_header.unit_length;

        const version = try fr.takeInt(u16, endian);
        var address_size: u8 = undefined;
        var debug_abbrev_offset: u64 = undefined;
        if (version == 5) {
            const unit_type = try fr.takeByte();
            if (unit_type != UT.compile) return bad();
            address_size = try fr.takeByte();
            debug_abbrev_offset = try readFormatSizedInt(&fr, unit_header.format, endian);
        } else if (version >= 2 and version < 5) {
            debug_abbrev_offset = try readFormatSizedInt(&fr, unit_header.format, endian);
            address_size = try fr.takeByte();
        } else {
            this_unit_offset += next_offset;
            continue;
        }

        const abbrev_table = try di.getAbbrevTable(gpa, debug_abbrev_offset);

        var max_attrs: usize = 0;
        for (abbrev_table.abbrevs) |abbrev| {
            max_attrs = @max(max_attrs, abbrev.attrs.len);
        }
        try attrs_buf.resize(max_attrs);

        var compile_unit_die = (try parseDie(
            &fr,
            attrs_buf.items,
            abbrev_table,
            unit_header.format,
            endian,
            address_size,
            version,
        )) orelse return bad();

        if (compile_unit_die.tag_id != DW.TAG.compile_unit) return bad();

        compile_unit_die.attrs = try gpa.dupe(Die.Attr, compile_unit_die.attrs);

        var compile_unit: CompileUnit = .{
            .offset = this_unit_offset,
            .size = next_offset,
            .version = version,
            .format = unit_header.format,
            .addr_size_bytes = address_size,
            .abbrev_offset = debug_abbrev_offset,
            .pc_range = null,
            .die = compile_unit_die,
            .str_offsets_base = if (compile_unit_die.getAttr(AT.str_offsets_base)) |fv| try fv.getUInt(usize) else 0,
            .addr_base = if (compile_unit_die.getAttr(AT.addr_base)) |fv| try fv.getUInt(usize) else 0,
            .rnglists_base = if (compile_unit_die.getAttr(AT.rnglists_base)) |fv| try fv.getUInt(usize) else 0,
            .loclists_base = if (compile_unit_die.getAttr(AT.loclists_base)) |fv| try fv.getUInt(usize) else 0,
            .frame_base = compile_unit_die.getAttr(AT.frame_base),
            .src_loc_cache = null,
        };

        compile_unit.pc_range = x: {
            if (compile_unit_die.getAttrAddr(di, endian, AT.low_pc, &compile_unit)) |low_pc| {
                if (compile_unit_die.getAttr(AT.high_pc)) |high_pc_value| {
                    const pc_end = switch (high_pc_value.*) {
                        .addr => |value| value,
                        .udata => |offset| low_pc + offset,
                        else => return bad(),
                    };
                    break :x PcRange{
                        .start = low_pc,
                        .end = pc_end,
                    };
                } else {
                    break :x null;
                }
            } else |err| {
                if (err != error.MissingDebugInfo) return err;
                break :x null;
            }
        };

        try di.compile_unit_list.append(gpa, compile_unit);

        this_unit_offset += next_offset;
    }
}

pub fn populateRanges(d: *Dwarf, gpa: Allocator, endian: Endian) ScanError!void {
    assert(d.ranges.items.len == 0);

    for (d.compile_unit_list.items, 0..) |*cu, cu_index| {
        if (cu.pc_range) |range| {
            try d.ranges.append(gpa, .{
                .start = range.start,
                .end = range.end,
                .compile_unit_index = cu_index,
            });
            continue;
        }
        const ranges_value = cu.die.getAttr(AT.ranges) orelse continue;
        var iter = DebugRangeIterator.init(ranges_value, d, endian, cu) catch continue;
        while (try iter.next()) |range| {
            // Not sure why LLVM thinks it's OK to emit these...
            if (range.start == range.end) continue;

            try d.ranges.append(gpa, .{
                .start = range.start,
                .end = range.end,
                .compile_unit_index = cu_index,
            });
        }
    }

    std.mem.sortUnstable(Range, d.ranges.items, {}, struct {
        pub fn lessThan(ctx: void, a: Range, b: Range) bool {
            _ = ctx;
            return a.start < b.start;
        }
    }.lessThan);
}

const DebugRangeIterator = struct {
    base_address: u64,
    section_type: Section.Id,
    di: *const Dwarf,
    endian: Endian,
    compile_unit: *const CompileUnit,
    fr: Reader,

    pub fn init(ranges_value: *const FormValue, di: *const Dwarf, endian: Endian, compile_unit: *const CompileUnit) !@This() {
        const section_type = if (compile_unit.version >= 5) Section.Id.debug_rnglists else Section.Id.debug_ranges;
        const debug_ranges = di.section(section_type) orelse return error.MissingDebugInfo;

        const ranges_offset = switch (ranges_value.*) {
            .sec_offset, .udata => |off| off,
            .rnglistx => |idx| off: {
                switch (compile_unit.format) {
                    .@"32" => {
                        const offset_loc = compile_unit.rnglists_base + 4 * idx;
                        if (offset_loc + 4 > debug_ranges.len) return bad();
                        const offset = mem.readInt(u32, debug_ranges[@intCast(offset_loc)..][0..4], endian);
                        break :off compile_unit.rnglists_base + offset;
                    },
                    .@"64" => {
                        const offset_loc = compile_unit.rnglists_base + 8 * idx;
                        if (offset_loc + 8 > debug_ranges.len) return bad();
                        const offset = mem.readInt(u64, debug_ranges[@intCast(offset_loc)..][0..8], endian);
                        break :off compile_unit.rnglists_base + offset;
                    },
                }
            },
            else => return bad(),
        };

        // All the addresses in the list are relative to the value
        // specified by DW_AT.low_pc or to some other value encoded
        // in the list itself.
        // If no starting value is specified use zero.
        const base_address = compile_unit.die.getAttrAddr(di, endian, AT.low_pc, compile_unit) catch |err| switch (err) {
            error.MissingDebugInfo => 0,
            else => return err,
        };

        var fr: Reader = .fixed(debug_ranges);
        fr.seek = cast(usize, ranges_offset) orelse return bad();

        return .{
            .base_address = base_address,
            .section_type = section_type,
            .di = di,
            .endian = endian,
            .compile_unit = compile_unit,
            .fr = fr,
        };
    }

    // Returns the next range in the list, or null if the end was reached.
    pub fn next(self: *@This()) !?PcRange {
        const endian = self.endian;
        const addr_size_bytes = self.compile_unit.addr_size_bytes;
        switch (self.section_type) {
            .debug_rnglists => {
                const kind = try self.fr.takeByte();
                switch (kind) {
                    RLE.end_of_list => return null,
                    RLE.base_addressx => {
                        const index = try self.fr.takeLeb128(u64);
                        self.base_address = try self.di.readDebugAddr(endian, self.compile_unit, index);
                        return try self.next();
                    },
                    RLE.startx_endx => {
                        const start_index = try self.fr.takeLeb128(u64);
                        const start_addr = try self.di.readDebugAddr(endian, self.compile_unit, start_index);

                        const end_index = try self.fr.takeLeb128(u64);
                        const end_addr = try self.di.readDebugAddr(endian, self.compile_unit, end_index);

                        return .{
                            .start = start_addr,
                            .end = end_addr,
                        };
                    },
                    RLE.startx_length => {
                        const start_index = try self.fr.takeLeb128(u64);
                        const start_addr = try self.di.readDebugAddr(endian, self.compile_unit, start_index);

                        const len = try self.fr.takeLeb128(u64);
                        const end_addr = start_addr + len;

                        return .{
                            .start = start_addr,
                            .end = end_addr,
                        };
                    },
                    RLE.offset_pair => {
                        const start_addr = try self.fr.takeLeb128(u64);
                        const end_addr = try self.fr.takeLeb128(u64);

                        // This is the only kind that uses the base address
                        return .{
                            .start = self.base_address + start_addr,
                            .end = self.base_address + end_addr,
                        };
                    },
                    RLE.base_address => {
                        self.base_address = try readAddress(&self.fr, endian, addr_size_bytes);
                        return try self.next();
                    },
                    RLE.start_end => {
                        const start_addr = try readAddress(&self.fr, endian, addr_size_bytes);
                        const end_addr = try readAddress(&self.fr, endian, addr_size_bytes);

                        return .{
                            .start = start_addr,
                            .end = end_addr,
                        };
                    },
                    RLE.start_length => {
                        const start_addr = try readAddress(&self.fr, endian, addr_size_bytes);
                        const len = try self.fr.takeLeb128(u64);
                        const end_addr = start_addr + len;

                        return .{
                            .start = start_addr,
                            .end = end_addr,
                        };
                    },
                    else => return bad(),
                }
            },
            .debug_ranges => {
                const start_addr = try readAddress(&self.fr, endian, addr_size_bytes);
                const end_addr = try readAddress(&self.fr, endian, addr_size_bytes);
                if (start_addr == 0 and end_addr == 0) return null;

                // The entry with start_addr = max_representable_address selects a new value for the base address
                const max_representable_address = ~@as(u64, 0) >> @intCast(64 - addr_size_bytes);
                if (start_addr == max_representable_address) {
                    self.base_address = end_addr;
                    return try self.next();
                }

                return .{
                    .start = self.base_address + start_addr,
                    .end = self.base_address + end_addr,
                };
            },
            else => unreachable,
        }
    }
};

/// TODO: change this to binary searching the sorted compile unit list
pub fn findCompileUnit(di: *const Dwarf, endian: Endian, target_address: u64) !*CompileUnit {
    for (di.compile_unit_list.items) |*compile_unit| {
        if (compile_unit.pc_range) |range| {
            if (target_address >= range.start and target_address < range.end) return compile_unit;
        }

        const ranges_value = compile_unit.die.getAttr(AT.ranges) orelse continue;
        var iter = DebugRangeIterator.init(ranges_value, di, endian, compile_unit) catch continue;
        while (try iter.next()) |range| {
            if (target_address >= range.start and target_address < range.end) return compile_unit;
        }
    }

    return missing();
}

/// Gets an already existing AbbrevTable given the abbrev_offset, or if not found,
/// seeks in the stream and parses it.
fn getAbbrevTable(di: *Dwarf, gpa: Allocator, abbrev_offset: u64) !*const Abbrev.Table {
    for (di.abbrev_table_list.items) |*table| {
        if (table.offset == abbrev_offset) {
            return table;
        }
    }
    try di.abbrev_table_list.append(
        gpa,
        try di.parseAbbrevTable(gpa, abbrev_offset),
    );
    return &di.abbrev_table_list.items[di.abbrev_table_list.items.len - 1];
}

fn parseAbbrevTable(di: *Dwarf, gpa: Allocator, offset: u64) !Abbrev.Table {
    var fr: Reader = .fixed(di.section(.debug_abbrev).?);
    fr.seek = cast(usize, offset) orelse return bad();

    var abbrevs: std.ArrayList(Abbrev) = .empty;
    defer {
        for (abbrevs.items) |*abbrev| {
            abbrev.deinit(gpa);
        }
        abbrevs.deinit(gpa);
    }

    var attrs: std.ArrayList(Abbrev.Attr) = .empty;
    defer attrs.deinit(gpa);

    while (true) {
        const code = try fr.takeLeb128(u64);
        if (code == 0) break;
        const tag_id = try fr.takeLeb128(u64);
        const has_children = (try fr.takeByte()) == DW.CHILDREN.yes;

        while (true) {
            const attr_id = try fr.takeLeb128(u64);
            const form_id = try fr.takeLeb128(u64);
            if (attr_id == 0 and form_id == 0) break;
            try attrs.append(gpa, .{
                .id = attr_id,
                .form_id = form_id,
                .payload = switch (form_id) {
                    FORM.implicit_const => try fr.takeLeb128(i64),
                    else => undefined,
                },
            });
        }
        try abbrevs.ensureUnusedCapacity(gpa, 1);
        abbrevs.appendAssumeCapacity(.{
            .code = code,
            .tag_id = tag_id,
            .has_children = has_children,
            .attrs = try attrs.toOwnedSlice(gpa),
        });
    }

    return .{
        .offset = offset,
        .abbrevs = try abbrevs.toOwnedSlice(gpa),
    };
}

fn parseDie(
    fr: *Reader,
    attrs_buf: []Die.Attr,
    abbrev_table: *const Abbrev.Table,
    format: Format,
    endian: Endian,
    addr_size_bytes: u8,
    version: u16,
) ScanError!?Die {
    const abbrev_code = try fr.takeLeb128(u64);
    if (abbrev_code == 0) return null;
    const table_entry = abbrev_table.get(abbrev_code) orelse return bad();

    const attrs = attrs_buf[0..table_entry.attrs.len];
    for (attrs, table_entry.attrs) |*result_attr, attr| result_attr.* = .{
        .id = attr.id,
        .value = try parseFormValue(fr, attr.form_id, format, endian, addr_size_bytes, attr.payload, version),
    };
    return .{
        .tag_id = table_entry.tag_id,
        .has_children = table_entry.has_children,
        .attrs = attrs,
    };
}

/// Ensures that addresses in the returned LineTable are monotonically increasing.
fn runLineNumberProgram(d: *Dwarf, gpa: Allocator, endian: Endian, compile_unit: *const CompileUnit) !CompileUnit.SrcLocCache {
    const compile_unit_cwd = try compile_unit.die.getAttrString(d, endian, AT.comp_dir, d.section(.debug_line_str), compile_unit);
    const line_info_offset = try compile_unit.die.getAttrSecOffset(AT.stmt_list);

    var fr: Reader = .fixed(d.section(.debug_line).?);
    fr.seek = @intCast(line_info_offset);

    const unit_header = try readUnitHeader(&fr, endian);
    if (unit_header.unit_length == 0) return missing();

    const next_offset = unit_header.header_length + unit_header.unit_length;

    const version = try fr.takeInt(u16, endian);
    if (version < 2) return bad();

    const addr_size_bytes: u8, const seg_size: u8 = if (version >= 5) .{
        try fr.takeByte(),
        try fr.takeByte(),
    } else .{
        compile_unit.addr_size_bytes,
        0,
    };
    if (seg_size != 0) return bad(); // unsupported

    const prologue_length = try readFormatSizedInt(&fr, unit_header.format, endian);
    const prog_start_offset = fr.seek + prologue_length;

    const minimum_instruction_length = try fr.takeByte();
    if (minimum_instruction_length == 0) return bad();

    if (version >= 4) {
        const maximum_operations_per_instruction = try fr.takeByte();
        _ = maximum_operations_per_instruction;
    }

    const default_is_stmt = (try fr.takeByte()) != 0;
    const line_base = try fr.takeByteSigned();

    const line_range = try fr.takeByte();
    if (line_range == 0) return bad();

    const opcode_base = try fr.takeByte();

    const standard_opcode_lengths = try fr.take(opcode_base - 1);

    var directories: ArrayList(FileEntry) = .empty;
    defer directories.deinit(gpa);
    var file_entries: ArrayList(FileEntry) = .empty;
    defer file_entries.deinit(gpa);

    if (version < 5) {
        try directories.append(gpa, .{ .path = compile_unit_cwd });

        while (true) {
            const dir = try fr.takeSentinel(0);
            if (dir.len == 0) break;
            try directories.append(gpa, .{ .path = dir });
        }

        while (true) {
            const file_name = try fr.takeSentinel(0);
            if (file_name.len == 0) break;
            const dir_index = try fr.takeLeb128(u32);
            const mtime = try fr.takeLeb128(u64);
            const size = try fr.takeLeb128(u64);
            try file_entries.append(gpa, .{
                .path = file_name,
                .dir_index = dir_index,
                .mtime = mtime,
                .size = size,
            });
        }
    } else {
        const FileEntFmt = struct {
            content_type_code: u16,
            form_code: u16,
        };
        {
            var dir_ent_fmt_buf: [10]FileEntFmt = undefined;
            const directory_entry_format_count = try fr.takeByte();
            if (directory_entry_format_count > dir_ent_fmt_buf.len) return bad();
            for (dir_ent_fmt_buf[0..directory_entry_format_count]) |*ent_fmt| {
                ent_fmt.* = .{
                    .content_type_code = try fr.takeLeb128(u8),
                    .form_code = try fr.takeLeb128(u16),
                };
            }

            const directories_count = try fr.takeLeb128(usize);

            for (try directories.addManyAsSlice(gpa, directories_count)) |*e| {
                e.* = .{ .path = &.{} };
                for (dir_ent_fmt_buf[0..directory_entry_format_count]) |ent_fmt| {
                    const form_value = try parseFormValue(&fr, ent_fmt.form_code, unit_header.format, endian, addr_size_bytes, null, version);
                    switch (ent_fmt.content_type_code) {
                        DW.LNCT.path => e.path = try form_value.getString(d.*),
                        DW.LNCT.directory_index => e.dir_index = try form_value.getUInt(u32),
                        DW.LNCT.timestamp => e.mtime = try form_value.getUInt(u64),
                        DW.LNCT.size => e.size = try form_value.getUInt(u64),
                        DW.LNCT.MD5 => e.md5 = switch (form_value) {
                            .data16 => |data16| data16.*,
                            else => return bad(),
                        },
                        else => continue,
                    }
                }
            }
        }

        var file_ent_fmt_buf: [10]FileEntFmt = undefined;
        const file_name_entry_format_count = try fr.takeByte();
        if (file_name_entry_format_count > file_ent_fmt_buf.len) return bad();
        for (file_ent_fmt_buf[0..file_name_entry_format_count]) |*ent_fmt| {
            ent_fmt.* = .{
                .content_type_code = try fr.takeLeb128(u16),
                .form_code = try fr.takeLeb128(u16),
            };
        }

        const file_names_count = try fr.takeLeb128(usize);
        try file_entries.ensureUnusedCapacity(gpa, file_names_count);

        for (try file_entries.addManyAsSlice(gpa, file_names_count)) |*e| {
            e.* = .{ .path = &.{} };
            for (file_ent_fmt_buf[0..file_name_entry_format_count]) |ent_fmt| {
                const form_value = try parseFormValue(&fr, ent_fmt.form_code, unit_header.format, endian, addr_size_bytes, null, version);
                switch (ent_fmt.content_type_code) {
                    DW.LNCT.path => e.path = try form_value.getString(d.*),
                    DW.LNCT.directory_index => e.dir_index = try form_value.getUInt(u32),
                    DW.LNCT.timestamp => e.mtime = try form_value.getUInt(u64),
                    DW.LNCT.size => e.size = try form_value.getUInt(u64),
                    DW.LNCT.MD5 => e.md5 = switch (form_value) {
                        .data16 => |data16| data16.*,
                        else => return bad(),
                    },
                    else => continue,
                }
            }
        }
    }

    const abbrev_table = try d.getAbbrevTable(gpa, compile_unit.abbrev_offset);
    const attrs_buf = try gpa.alloc(Die.Attr, max_attrs: {
        var max_attrs: usize = 0;
        for (abbrev_table.abbrevs) |abbrev| {
            max_attrs = @max(max_attrs, abbrev.attrs.len);
        }
        break :max_attrs max_attrs;
    });
    defer gpa.free(attrs_buf);

    var prog = LineNumberProgram.init(default_is_stmt, version);
    var line_table: CompileUnit.SrcLocCache.LineTable = .{};
    errdefer line_table.deinit(gpa);

    fr.seek = @intCast(prog_start_offset);

    const next_unit_pos = line_info_offset + next_offset;

    while (fr.seek < next_unit_pos) {
        const opcode = try fr.takeByte();

        if (opcode == DW.LNS.extended_op) {
            const op_size = try fr.takeLeb128(u64);
            if (op_size < 1) return bad();
            const sub_op = try fr.takeByte();
            switch (sub_op) {
                DW.LNE.end_sequence => {
                    // The row being added here is an "end" address, meaning
                    // that it does not map to the source location here -
                    // rather it marks the previous address as the last address
                    // that maps to this source location.

                    // In this implementation we don't mark end of addresses.
                    // This is a performance optimization based on the fact
                    // that we don't need to know if an address is missing
                    // source location info; we are only interested in being
                    // able to look up source location info for addresses that
                    // are known to have debug info.
                    //if (debug_debug_mode) assert(!line_table.contains(prog.address));
                    //try line_table.put(gpa, prog.address, CompileUnit.SrcLocCache.LineEntry.invalid);
                    prog.reset();
                },
                DW.LNE.set_address => {
                    prog.address = try readAddress(&fr, endian, addr_size_bytes);
                },
                DW.LNE.define_file => {
                    const path = try fr.takeSentinel(0);
                    const dir_index = try fr.takeLeb128(u32);
                    const mtime = try fr.takeLeb128(u64);
                    const size = try fr.takeLeb128(u64);
                    try file_entries.append(gpa, .{
                        .path = path,
                        .dir_index = dir_index,
                        .mtime = mtime,
                        .size = size,
                    });
                },
                DW.LNE.ZIG_set_decl => {
                    const decl_die_offset = try readFormatSizedInt(&fr, unit_header.format, endian);
                    var di_fr: Reader = .fixed(d.section(.debug_info) orelse continue);
                    di_fr.seek = @intCast(decl_die_offset);
                    var die = (try parseDie(
                        &di_fr,
                        attrs_buf,
                        abbrev_table,
                        unit_header.format,
                        endian,
                        addr_size_bytes,
                        compile_unit.version,
                    )) orelse continue;
                    if (die.getAttr(AT.low_pc)) |_| {
                        prog.address = try die.getAttrAddr(d, endian, AT.low_pc, compile_unit);
                    }
                    if (die.getAttr(AT.decl_line)) |decl_line| {
                        prog.line = try decl_line.getUInt(i64);
                    }
                    if (die.getAttr(AT.decl_column)) |decl_column| {
                        prog.column = try decl_column.getUInt(u64);
                    }
                    while (die.getAttr(AT.decl_file) == null) {
                        if (die.getAttr(AT.abstract_origin)) |_| {
                            di_fr.seek = @intCast(try die.getAttrRef(
                                AT.abstract_origin,
                                compile_unit.offset,
                                compile_unit.size,
                            ));
                        } else if (die.getAttr(AT.specification)) |_| {
                            di_fr.seek = @intCast(try die.getAttrRef(
                                AT.specification,
                                compile_unit.offset,
                                compile_unit.size,
                            ));
                        } else if (die.getAttr(AT.ZIG_parent)) |_| {
                            di_fr.seek = @intCast(try die.getAttrRef(
                                AT.ZIG_parent,
                                compile_unit.offset,
                                compile_unit.size,
                            ));
                        } else {
                            // no parent, so we can't find DW_AT_decl_file
                            break;
                        }
                        die = (try parseDie(
                            &di_fr,
                            attrs_buf,
                            abbrev_table,
                            unit_header.format,
                            endian,
                            addr_size_bytes,
                            compile_unit.version,
                        )) orelse break;
                    } else {
                        prog.file = try die.getAttr(AT.decl_file).?.getUInt(usize);
                    }
                },
                else => try fr.discardAll64(op_size - 1),
            }
        } else if (opcode >= opcode_base) {
            // special opcodes
            const adjusted_opcode = opcode - opcode_base;
            const inc_addr = minimum_instruction_length * (adjusted_opcode / line_range);
            const inc_line = @as(i32, line_base) + @as(i32, adjusted_opcode % line_range);
            prog.line += inc_line;
            prog.address += inc_addr;
            try prog.addRow(gpa, &line_table);
            prog.basic_block = false;
        } else {
            switch (opcode) {
                DW.LNS.copy => {
                    try prog.addRow(gpa, &line_table);
                    prog.basic_block = false;
                },
                DW.LNS.advance_pc => {
                    const arg = try fr.takeLeb128(u64);
                    prog.address += arg * minimum_instruction_length;
                },
                DW.LNS.advance_line => {
                    const arg = try fr.takeLeb128(i64);
                    prog.line += arg;
                },
                DW.LNS.set_file => {
                    const arg = try fr.takeLeb128(usize);
                    prog.file = arg;
                },
                DW.LNS.set_column => {
                    const arg = try fr.takeLeb128(u64);
                    prog.column = arg;
                },
                DW.LNS.negate_stmt => {
                    prog.is_stmt = !prog.is_stmt;
                },
                DW.LNS.set_basic_block => {
                    prog.basic_block = true;
                },
                DW.LNS.const_add_pc => {
                    const inc_addr = minimum_instruction_length * ((255 - opcode_base) / line_range);
                    prog.address += inc_addr;
                },
                DW.LNS.fixed_advance_pc => {
                    const arg = try fr.takeInt(u16, endian);
                    prog.address += arg;
                },
                DW.LNS.set_prologue_end => {},
                else => {
                    if (opcode - 1 >= standard_opcode_lengths.len) return bad();
                    try fr.discardAll(standard_opcode_lengths[opcode - 1]);
                },
            }
        }
    }

    // Dwarf standard v5, 6.2.5 says
    // > Within a sequence, addresses and operation pointers may only increase.
    // However, this is empirically not the case in reality, so we sort here.
    line_table.sortUnstable(struct {
        keys: []const u64,

        pub fn lessThan(ctx: @This(), a_index: usize, b_index: usize) bool {
            return ctx.keys[a_index] < ctx.keys[b_index];
        }
    }{ .keys = line_table.keys() });

    try directories.shrinkToLen(gpa);
    try file_entries.shrinkToLen(gpa);

    return .{
        .line_table = line_table,
        .directories = directories.toOwnedSliceAssert(),
        .files = file_entries.toOwnedSliceAssert(),
        .version = version,
    };
}

pub fn populateSrcLocCache(d: *Dwarf, gpa: Allocator, endian: Endian, cu: *CompileUnit) ScanError!void {
    if (cu.src_loc_cache != null) return;
    cu.src_loc_cache = try d.runLineNumberProgram(gpa, endian, cu);
}

pub fn getLineNumberInfo(
    d: *Dwarf,
    gpa: Allocator,
    text_arena: Allocator,
    endian: Endian,
    compile_unit: *CompileUnit,
    target_address: u64,
) !std.debug.SourceLocation {
    try d.populateSrcLocCache(gpa, endian, compile_unit);
    const slc = &compile_unit.src_loc_cache.?;
    const entry = try slc.findSource(target_address);
    const file_index = entry.file - @intFromBool(slc.version < 5);
    if (file_index >= slc.files.len) return bad();
    const file_entry = &slc.files[file_index];
    if (file_entry.dir_index >= slc.directories.len) return bad();
    const dir_name = slc.directories[file_entry.dir_index].path;
    const file_name = try std.fs.path.join(text_arena, &.{ dir_name, file_entry.path });
    return .{
        .line = entry.line,
        .column = entry.column,
        .file_name = file_name,
    };
}

fn getString(di: Dwarf, offset: u64) ![:0]const u8 {
    return getStringGeneric(di.section(.debug_str), offset);
}

fn getLineString(di: Dwarf, offset: u64) ![:0]const u8 {
    return getStringGeneric(di.section(.debug_line_str), offset);
}

fn readDebugAddr(di: Dwarf, endian: Endian, compile_unit: *const CompileUnit, index: u64) !u64 {
    const debug_addr = di.section(.debug_addr) orelse return bad();

    // addr_base points to the first item after the header, however we
    // need to read the header to know the size of each item. Empirically,
    // it may disagree with is_64 on the compile unit.
    // The header is 8 or 12 bytes depending on is_64.
    if (compile_unit.addr_base < 8) return bad();

    const version = mem.readInt(u16, debug_addr[compile_unit.addr_base - 4 ..][0..2], endian);
    if (version != 5) return bad();

    const addr_size = debug_addr[compile_unit.addr_base - 2];
    const seg_size = debug_addr[compile_unit.addr_base - 1];

    const byte_offset = compile_unit.addr_base + (addr_size + seg_size) * index;
    if (byte_offset + addr_size > debug_addr.len) return bad();
    return switch (addr_size) {
        1 => debug_addr[@intCast(byte_offset)],
        2 => mem.readInt(u16, debug_addr[@intCast(byte_offset)..][0..2], endian),
        4 => mem.readInt(u32, debug_addr[@intCast(byte_offset)..][0..4], endian),
        8 => mem.readInt(u64, debug_addr[@intCast(byte_offset)..][0..8], endian),
        else => bad(),
    };
}

fn parseFormValue(
    r: *Reader,
    form_id: u64,
    format: Format,
    endian: Endian,
    addr_size_bytes: u8,
    implicit_const: ?i64,
    version: u16,
) ScanError!FormValue {
    return switch (form_id) {
        // DWARF5.pdf page 213: the size of this value is encoded in the
        // compilation unit header as address size.
        FORM.addr => .{ .addr = try readAddress(r, endian, addr_size_bytes) },
        FORM.addrx1 => .{ .addrx = try r.takeByte() },
        FORM.addrx2 => .{ .addrx = try r.takeInt(u16, endian) },
        FORM.addrx3 => .{ .addrx = try r.takeInt(u24, endian) },
        FORM.addrx4 => .{ .addrx = try r.takeInt(u32, endian) },
        FORM.addrx => .{ .addrx = try r.takeLeb128(u64) },

        FORM.block1 => .{ .block = try r.take(try r.takeByte()) },
        FORM.block2 => .{ .block = try r.take(try r.takeInt(u16, endian)) },
        FORM.block4 => .{ .block = try r.take(try r.takeInt(u32, endian)) },
        FORM.block => .{ .block = try r.take(try r.takeLeb128(usize)) },

        FORM.data1 => .{ .udata = try r.takeByte() },
        FORM.data2 => .{ .udata = try r.takeInt(u16, endian) },
        FORM.data4 => .{ .udata = try r.takeInt(u32, endian) },
        FORM.data8 => .{ .udata = try r.takeInt(u64, endian) },
        FORM.data16 => .{ .data16 = try r.takeArray(16) },
        FORM.udata => .{ .udata = try r.takeLeb128(u64) },
        FORM.sdata => .{ .sdata = try r.takeLeb128(i64) },
        FORM.exprloc => .{ .exprloc = try r.take(try r.takeLeb128(usize)) },
        FORM.flag => .{ .flag = (try r.takeByte()) != 0 },
        FORM.flag_present => .{ .flag = true },
        FORM.sec_offset => .{ .sec_offset = try readFormatSizedInt(r, format, endian) },

        FORM.ref1 => .{ .ref = try r.takeByte() },
        FORM.ref2 => .{ .ref = try r.takeInt(u16, endian) },
        FORM.ref4 => .{ .ref = try r.takeInt(u32, endian) },
        FORM.ref8 => .{ .ref = try r.takeInt(u64, endian) },
        FORM.ref_udata => .{ .ref = try r.takeLeb128(u64) },

        FORM.ref_addr => .{
            .ref_addr = switch (version) {
                2 => try readAddress(r, endian, addr_size_bytes),
                else => try readFormatSizedInt(r, format, endian),
            },
        },
        FORM.ref_sig8 => .{ .ref = try r.takeInt(u64, endian) },

        FORM.string => .{ .string = try r.takeSentinel(0) },
        FORM.strp => .{ .strp = try readFormatSizedInt(r, format, endian) },
        FORM.strx1 => .{ .strx = try r.takeByte() },
        FORM.strx2 => .{ .strx = try r.takeInt(u16, endian) },
        FORM.strx3 => .{ .strx = try r.takeInt(u24, endian) },
        FORM.strx4 => .{ .strx = try r.takeInt(u32, endian) },
        FORM.strx => .{ .strx = try r.takeLeb128(usize) },
        FORM.line_strp => .{ .line_strp = try readFormatSizedInt(r, format, endian) },
        FORM.indirect => parseFormValue(r, try r.takeLeb128(u64), format, endian, addr_size_bytes, implicit_const, version),
        FORM.implicit_const => .{ .sdata = implicit_const orelse return bad() },
        FORM.loclistx => .{ .loclistx = try r.takeLeb128(u64) },
        FORM.rnglistx => .{ .rnglistx = try r.takeLeb128(u64) },
        else => {
            //debug.print("unrecognized form id: {x}\n", .{form_id});
            return bad();
        },
    };
}

const FileEntry = struct {
    path: []const u8,
    dir_index: u32 = 0,
    mtime: u64 = 0,
    size: u64 = 0,
    md5: [16]u8 = @splat(0),
};

const LineNumberProgram = struct {
    address: u64,
    file: usize,
    line: i64,
    column: u64,
    version: u16,
    is_stmt: bool,
    basic_block: bool,

    default_is_stmt: bool,

    // Reset the state machine following the DWARF specification
    pub fn reset(self: *LineNumberProgram) void {
        self.address = 0;
        self.file = 1;
        self.line = 1;
        self.column = 0;
        self.is_stmt = self.default_is_stmt;
        self.basic_block = false;
    }

    pub fn init(is_stmt: bool, version: u16) LineNumberProgram {
        return .{
            .address = 0,
            .file = 1,
            .line = 1,
            .column = 0,
            .version = version,
            .is_stmt = is_stmt,
            .basic_block = false,
            .default_is_stmt = is_stmt,
        };
    }

    pub fn addRow(prog: *LineNumberProgram, gpa: Allocator, table: *CompileUnit.SrcLocCache.LineTable) !void {
        if (prog.line == 0) {
            //if (debug_debug_mode) @panic("garbage line data");
            return;
        }
        if (debug_debug_mode) assert(!table.contains(prog.address));
        try table.put(gpa, prog.address, .{
            .line = cast(u32, prog.line) orelse maxInt(u32),
            .column = cast(u32, prog.column) orelse maxInt(u32),
            .file = cast(u32, prog.file) orelse return bad(),
        });
    }
};

const UnitHeader = struct {
    format: Format,
    header_length: u4,
    unit_length: u64,
};

pub fn readUnitHeader(r: *Reader, endian: Endian) ScanError!UnitHeader {
    return switch (try r.takeInt(u32, endian)) {
        0...0xfffffff0 - 1 => |unit_length| .{
            .format = .@"32",
            .header_length = 4,
            .unit_length = unit_length,
        },
        0xfffffff0...0xffffffff - 1 => bad(),
        0xffffffff => .{
            .format = .@"64",
            .header_length = 12,
            .unit_length = try r.takeInt(u64, endian),
        },
    };
}

/// Returns the DWARF register number for an x86_64 register number found in compact unwind info
pub fn compactUnwindToDwarfRegNumber(unwind_reg_number: u3) !u16 {
    return switch (unwind_reg_number) {
        1 => 3, // RBX
        2 => 12, // R12
        3 => 13, // R13
        4 => 14, // R14
        5 => 15, // R15
        6 => 6, // RBP
        else => error.InvalidRegister,
    };
}

/// Returns `null` for CPU architectures without an instruction pointer register.
pub fn ipRegNum(arch: std.Target.Cpu.Arch) ?u16 {
    return switch (arch) {
        .aarch64, .aarch64_be => 32,
        .alpha => 64,
        .arc, .arceb => 160,
        .arm, .armeb, .thumb, .thumbeb => 15,
        .csky => 64,
        .hexagon => 76,
        .kvx => 64,
        .lanai => 2,
        .loongarch32, .loongarch64 => 64,
        .m68k => 26,
        .m88k => 64,
        .mips, .mipsel, .mips64, .mips64el => 66,
        .or1k => 35,
        .powerpc, .powerpcle, .powerpc64, .powerpc64le => 67,
        .riscv32, .riscv32be, .riscv64, .riscv64be => 65,
        .s390x => 65,
        .sparc, .sparc64 => 65,
        .ve => 144,
        .x86 => 8,
        .x86_64 => 16,
        else => null,
    };
}

pub fn fpRegNum(arch: std.Target.Cpu.Arch) u16 {
    return switch (arch) {
        .aarch64, .aarch64_be => 29,
        .alpha => 15,
        .arc, .arceb => 27,
        .arm, .armeb, .thumb, .thumbeb => 11,
        .csky => 14,
        .hexagon => 30,
        .kvx => 14,
        .lanai => 5,
        .loongarch32, .loongarch64 => 22,
        .m68k => 14,
        .m88k => 30,
        .mips, .mipsel, .mips64, .mips64el => 30,
        .or1k => 2,
        .powerpc, .powerpcle, .powerpc64, .powerpc64le => 1,
        .riscv32, .riscv32be, .riscv64, .riscv64be => 8,
        .s390x => 11,
        .sparc, .sparc64 => 30,
        .ve => 9,
        .x86 => 5,
        .x86_64 => 6,
        else => unreachable,
    };
}

pub fn spRegNum(arch: std.Target.Cpu.Arch) u16 {
    return switch (arch) {
        .aarch64, .aarch64_be => 31,
        .alpha => 30,
        .arc, .arceb => 28,
        .arm, .armeb, .thumb, .thumbeb => 13,
        .csky => 14,
        .hexagon => 29,
        .kvx => 12,
        .lanai => 4,
        .loongarch32, .loongarch64 => 3,
        .m68k => 15,
        .m88k => 31,
        .mips, .mipsel, .mips64, .mips64el => 29,
        .or1k => 1,
        .powerpc, .powerpcle, .powerpc64, .powerpc64le => 1,
        .riscv32, .riscv32be, .riscv64, .riscv64be => 2,
        .s390x => 15,
        .sparc, .sparc64 => 14,
        .ve => 11,
        .x86 => 4,
        .x86_64 => 7,
        else => unreachable,
    };
}

/// Tells whether unwinding for this target is supported by the Dwarf standard.
///
/// See also `std.debug.SelfInfo.can_unwind` which tells whether the Zig standard
/// library has a working implementation of unwinding for the current target.
pub fn supportsUnwinding(target: *const std.Target) bool {
    return switch (target.cpu.arch) {
        .amdgcn,
        .nvptx,
        .nvptx64,
        .spirv32,
        .spirv64,
        => false,

        // Conservative guess. Feel free to update this logic with any targets
        // that are known to not support Dwarf unwinding.
        else => true,
    };
}

/// This function is to make it handy to comment out the return and make it
/// into a crash when working on this file.
pub fn bad() error{InvalidDebugInfo} {
    invalidDebugInfoDetected();
    return error.InvalidDebugInfo;
}

pub fn invalidDebugInfoDetected() void {
    if (debug_debug_mode) @panic("bad dwarf");
}

pub fn missing() error{MissingDebugInfo} {
    if (debug_debug_mode) @panic("missing dwarf");
    return error.MissingDebugInfo;
}

fn getStringGeneric(opt_str: ?[]const u8, offset: u64) ![:0]const u8 {
    const str = opt_str orelse return bad();
    if (offset > str.len) return bad();
    const casted_offset = cast(usize, offset) orelse return bad();
    // Valid strings always have a terminating zero byte
    const last = std.mem.findScalarPos(u8, str, casted_offset, 0) orelse return bad();
    return str[casted_offset..last :0];
}

pub fn getSymbols(
    di: *Dwarf,
    symbol_allocator: Allocator,
    text_arena: Allocator,
    endian: Endian,
    address: u64,
    resolve_inline_callers: bool,
    symbols: *std.ArrayList(std.debug.Symbol),
) std.debug.SelfInfoError!void {
    _ = resolve_inline_callers;
    const gpa = std.debug.getDebugInfoAllocator();

    const compile_unit = di.findCompileUnit(endian, address) catch |err| switch (err) {
        error.EndOfStream => return error.MissingDebugInfo,
        error.Overflow => return error.InvalidDebugInfo,
        error.ReadFailed, error.InvalidDebugInfo, error.MissingDebugInfo => |e| return e,
    };
    try symbols.append(symbol_allocator, .{
        .name = di.getSymbolName(address),
        .compile_unit_name = compile_unit.die.getAttrString(di, endian, std.dwarf.AT.name, di.section(.debug_str), compile_unit) catch |err| switch (err) {
            error.MissingDebugInfo, error.InvalidDebugInfo => null,
        },
        .source_location = di.getLineNumberInfo(gpa, text_arena, endian, compile_unit, address) catch |err| switch (err) {
            error.MissingDebugInfo, error.InvalidDebugInfo => null,
            error.ReadFailed,
            error.EndOfStream,
            error.Overflow,
            error.StreamTooLong,
            => return error.InvalidDebugInfo,
            else => |e| return e,
        },
    });
}

/// DWARF5 7.4: "In the 32-bit DWARF format, all values that represent lengths of DWARF sections and
/// offsets relative to the beginning of DWARF sections are represented using four bytes. In the
/// 64-bit DWARF format, all values that represent lengths of DWARF sections and offsets relative to
/// the beginning of DWARF sections are represented using eight bytes".
///
/// This function is for reading such values.
fn readFormatSizedInt(r: *Reader, format: std.dwarf.Format, endian: Endian) !u64 {
    return switch (format) {
        .@"32" => try r.takeInt(u32, endian),
        .@"64" => try r.takeInt(u64, endian),
    };
}

fn readAddress(r: *Reader, endian: Endian, addr_size_bytes: u8) !u64 {
    return switch (addr_size_bytes) {
        2 => try r.takeInt(u16, endian),
        4 => try r.takeInt(u32, endian),
        8 => try r.takeInt(u64, endian),
        else => return bad(),
    };
}