dwarf

Documentation

Overview

Package dwarf provides DWARF debug information parsing for Soroban contract debugging. It extracts local variable information from WASM files with debug symbols to help reconstruct variable values at the point of a trap (e.g., memory-out-of-bounds).

Index

• Variables
• type Frame
• type InlinedSubroutineInfo
• type LocalVar
• type Parser
  • func NewParser(data []byte) (*Parser, error)
  • func (p *Parser) BinaryType() string
  • func (p *Parser) FindLocalVarsAt(addr uint64) ([]LocalVar, error)
  • func (p *Parser) FindSubprogramAt(addr uint64) (*SubprogramInfo, error)
  • func (p *Parser) GetInlinedSubroutines(spOffset dwarf.Offset) ([]InlinedSubroutineInfo, error)
  • func (p *Parser) GetSourceLocation(addr uint64) (*SourceLocation, error)
  • func (p *Parser) GetSubprograms() ([]SubprogramInfo, error)
  • func (p *Parser) HasDebugInfo() bool
  • func (p *Parser) ResolveInlinedChain(addr uint64) ([]InlinedSubroutineInfo, error)
• type SourceLocation
• type SubprogramInfo

Variables

var (
	// ErrNoDebugInfo indicates the binary doesn't contain DWARF debug information
	ErrNoDebugInfo = errors.New("no DWARF debug information found")
	// ErrNoLocalVars indicates no local variables were found at the given address
	ErrNoLocalVars = errors.New("no local variables found at address")
	// ErrInvalidWASM indicates the file is not a valid WASM or ELF binary
	ErrInvalidWASM = errors.New("invalid WASM or ELF binary")
)

Types

type Frame

type Frame struct {
	Function     string
	SourceLoc    SourceLocation
	LocalVars    []LocalVar
	ReturnAddr   uint64
	FramePointer uint64
}

Frame represents a stack frame with local variable information

type InlinedSubroutineInfo

type InlinedSubroutineInfo struct {
	Name            string         // Function name
	DemangledName   string         // Demangled function name
	CallSite        SourceLocation // Where the call was written in the caller's source
	InlinedLocation SourceLocation // Source location inside the inlined body
	LowPC           uint64         // Start address of the inlined code
	HighPC          uint64         // End address of the inlined code
}

InlinedSubroutineInfo represents an inlined subroutine in the DWARF tree.

type LocalVar

type LocalVar struct {
	Name          string      // Variable name (may be mangled)
	DemangledName string      // Demangled name for display
	Type          string      // Type name
	Location      string      // DWARF location description
	Value         interface{} // Computed value (if available)
	Address       uint64      // Memory address (if applicable)
	StartLine     int         // Source line where variable is in scope
	EndLine       int         // Source line where variable goes out of scope
}

LocalVar represents a local variable at a specific program location

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser handles DWARF debug information extraction

func NewParser

func NewParser(data []byte) (*Parser, error)

NewParser creates a new DWARF parser from a binary

func (*Parser) BinaryType

func (p *Parser) BinaryType() string

BinaryType returns the type of binary being parsed

func (*Parser) FindLocalVarsAt

func (p *Parser) FindLocalVarsAt(addr uint64) ([]LocalVar, error)

FindLocalVarsAt finds local variables visible at the given address

func (*Parser) FindSubprogramAt

func (p *Parser) FindSubprogramAt(addr uint64) (*SubprogramInfo, error)

FindSubprogramAt finds the subprogram containing the given address

func (*Parser) GetInlinedSubroutines

func (p *Parser) GetInlinedSubroutines(spOffset dwarf.Offset) ([]InlinedSubroutineInfo, error)

GetInlinedSubroutines returns all inlined subroutines found inside the subprogram at the given DWARF offset. When no inlined subroutines exist an empty (non-nil) slice is returned.

func (*Parser) GetSourceLocation

func (p *Parser) GetSourceLocation(addr uint64) (*SourceLocation, error)

GetSourceLocation finds the source location for a given address. It uses the standard library's debug/dwarf line reader.

func (*Parser) GetSubprograms

func (p *Parser) GetSubprograms() ([]SubprogramInfo, error)

GetSubprograms returns all subprograms (functions) in the debug info

func (*Parser) HasDebugInfo

func (p *Parser) HasDebugInfo() bool

HasDebugInfo returns true if the binary contains DWARF debug information

func (*Parser) ResolveInlinedChain

func (p *Parser) ResolveInlinedChain(addr uint64) ([]InlinedSubroutineInfo, error)

ResolveInlinedChain resolves the inlined subroutine chain for a given instruction address. It finds the containing subprogram and then returns all inlined subroutines whose address range covers addr, ordered from outermost to innermost.

type SourceLocation

type SourceLocation struct {
	File   string
	Line   int
	Column int
}

SourceLocation represents a location in the source code

type SubprogramInfo

type SubprogramInfo struct {
	Name           string
	DemangledName  string
	LowPC          uint64
	HighPC         uint64
	Line           int
	File           string
	LocalVariables []LocalVar
}

SubprogramInfo represents a function/subprogram's debug information