dwarf

package
v0.32.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 14, 2024 License: GPL-3.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source 
const DriverFunctionName = "<driver>"

DriverFunctionName is the name given to a function that represents all the instructions that fall outside of the ROM and are in fact in the "driver".

Variables

View Source 
var UnsupportedDWARF = errors.New("unsupported DWARF")

Sentinal error to indicate that the DWARF data isn't supported by the package. It might be valid DWARF but we don't want to deal with it

Functions

This section is empty.

Types

type AllSourceLines 

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

func (AllSourceLines) Get 

func (a AllSourceLines) Get(i int) *SourceLine

func (AllSourceLines) Len 

func (a AllSourceLines) Len() int

func (AllSourceLines) String 

func (a AllSourceLines) String(i int) string

type Cartridge 

type Cartridge interface {
	GetCoProcBus() coprocessor.CartCoProcBus
}

Cartridge defines the interface to the cartridge required by the source package

type FunctionFilter 

type FunctionFilter struct {
	FunctionName string
	Function     *SourceFunction
	Lines        SortedLines
}

type SortFunctionsMethod added in v0.30.0 

type SortFunctionsMethod int

SortFunctionsMethod specifies the sort method to be applied when sorting the entries in the SortedFunctions type 

const (
	SortFunctionsFile SortFunctionsMethod = iota
	SortFunctionsName
	SortFunctionsFrameCycles
	SortFunctionsAverageCycles
	SortFunctionsMaxCycles
	SortFunctionsFrameCalls
	SortFunctionsAverageCalls
	SortFunctionsMaxCalls
	SortFunctionsFrameCyclesPerCall
	SortFunctionsAverageCyclesPerCall
	SortFunctionsMaxCyclesPerCall
)

List of valid SortFunctionsMethod values

type SortLinesMethod added in v0.30.0 

type SortLinesMethod int

SortLinesMethod specifies the sort method to be applied when sorting the entries in the SortedLines type 

const (
	SortLinesFile SortLinesMethod = iota
	SortLinesFunction
	SortLinesNumber
	SortLinesFrameCycles
	SortLinesAverageCycles
	SortLinesMaxCycles
)

List of valid SortLinesMethod values

type SortVariablesMethod added in v0.30.0 

type SortVariablesMethod int

SortVariablesMethod specifies the sort method to be applied when sorting the entries in the SortedVariables type 

const (
	SortVariablesName SortVariablesMethod = iota
	SortVariablesAddress
)

List of valid SortVariablesMethod values

type SortedFunctions 

type SortedFunctions struct {
	Functions []*SourceFunction
	// contains filtered or unexported fields
}

SortedFunctions holds the list of SourceFunction sorted by the specfied method

func (SortedFunctions) Len 

func (e SortedFunctions) Len() int

Len implements the sort.Interface

func (SortedFunctions) Less 

func (e SortedFunctions) Less(i int, j int) bool

Less implements the sort.Interface

func (*SortedFunctions) Sort 

func (e *SortedFunctions) Sort(method SortFunctionsMethod, cumulative bool, load bool, descending bool, focus profiling.Focus)

Sort is a stable sort of the Functions in the SortedFunctions type

The cumulative and load parameters only apply to sort methods that work on the number of cycles

func (SortedFunctions) Swap 

func (e SortedFunctions) Swap(i int, j int)

Swap implements the sort.Interface

type SortedLines 

type SortedLines struct {
	Lines []*SourceLine
	// contains filtered or unexported fields
}

SortedLines holds the list of SourceLines sorted by the specfied method

func (SortedLines) Len 

func (e SortedLines) Len() int

func (SortedLines) Less 

func (e SortedLines) Less(i int, j int) bool

func (*SortedLines) Sort 

func (e *SortedLines) Sort(method SortLinesMethod, overProgram bool, load bool, descending bool, focus profiling.Focus)

Sort is a stable sort of the Lines in the SortedLines type

The overProgram and load parameters only apply to sort methods that work on the number of cycles

func (SortedLines) Swap 

func (e SortedLines) Swap(i int, j int)

type SortedVariables 

type SortedVariables struct {
	Variables []*SourceVariable
	// contains filtered or unexported fields
}

SortedVariables holds the list of SourceVariable sorted by the specfied method

func (SortedVariables) Len 

func (v SortedVariables) Len() int

Len implements the sort.Interface

func (SortedVariables) Less 

func (v SortedVariables) Less(i int, j int) bool

Less implements the sort.Interface

func (*SortedVariables) Sort added in v0.30.0 

func (e *SortedVariables) Sort(method SortVariablesMethod, descending bool)

Sort is a stable sort of the Variables in the SortedVariables type

func (SortedVariables) Swap 

func (v SortedVariables) Swap(i int, j int)

Swap implements the sort.Interface

type SortedVariablesLocal 

type SortedVariablesLocal struct {
	Variables []*SourceVariableLocal
	// contains filtered or unexported fields
}

SortedVariablesLocal holds the list of SourceVariableLocal sorted by the specfied method

This is exactly the same type and implementation as SortedVariables. With a bit of work this could probably be improved with an variable interface that handles both SourceVariable and SourceVariableLocal

func (SortedVariablesLocal) Len 

func (v SortedVariablesLocal) Len() int

Len implements the sort.Interface

func (SortedVariablesLocal) Less 

func (v SortedVariablesLocal) Less(i int, j int) bool

Less implements the sort.Interface

func (*SortedVariablesLocal) Sort added in v0.30.0 

func (e *SortedVariablesLocal) Sort(method SortVariablesMethod, descending bool)

Sort is a stable sort of the Variables in the SortedVariablesLocal type

func (SortedVariablesLocal) Swap 

func (v SortedVariablesLocal) Swap(i int, j int)

Swap implements the sort.Interface

type Source 

type Source struct {

	// source is compiled with optimisation
	Optimised bool

	// instructions in the source code
	Instructions map[uint64]*SourceInstruction

	// all the files in all the compile units
	Files     map[string]*SourceFile
	Filenames []string

	// as above but indexed by the file's short filename, which is sometimes
	// more useful than the full name
	//
	// short filenames also only include files that are in the same path as the
	// ROM file
	FilesByShortname map[string]*SourceFile
	ShortFilenames   []string

	// functions found in the compile units
	Functions     map[string]*SourceFunction
	FunctionNames []string

	// best guess at what the "main" function is in the program. very often
	// this function will be called "main" and will be easy to discern but
	// sometimes it is named something else and we must figure out as best we
	// can which function it is
	//
	// if no function can be found at all, MainFunction will be a stub entry
	MainFunction *SourceFunction

	// special purpose line used to collate instructions that are outside the
	// loaded ROM and are very likely instructions handled by the "driver". the
	// actual driver function is in the Functions map as normal, under the name
	// given in "const driverFunction"
	DriverSourceLine *SourceLine

	// sorted list of every function in all compile unit
	SortedFunctions SortedFunctions

	// all global variables in all compile units
	GlobalsByAddress map[uint64]*SourceVariable
	SortedGlobals    SortedVariables

	// all local variables in all compile units
	SortedLocals SortedVariablesLocal

	// the highest address of any variable (not just global variables, any
	// variable)
	HighAddress uint64

	// lines of source code found in the compile units. this is a sparse
	// coverage of the total address space
	LinesByAddress map[uint64]*SourceLine

	// sorted list of every source line in all compile units
	SortedLines SortedLines

	// every non-blank line of source code in all compile units
	AllLines AllSourceLines

	// sorted lines filtered by function name
	FunctionFilters []*FunctionFilter

	// profiling for the entire program
	Cycles profiling.Cycles

	// flag to indicate whether the execution profile has changed since it was cleared
	//
	// cheap and easy way to prevent sorting too often - rather than sort after
	// every call to execute(), we can use this flag to sort only when we need
	// to in the GUI.
	//
	// probably not scalable but sufficient for our needs of a single GUI
	// running and using the profiling data for only one reason
	ProfilingDirty bool
	// contains filtered or unexported fields
}

Source is created from available DWARF data that has been found in relation to and ELF file that looks to be related to the specified ROM.

It is possible for the arrays/map fields to be empty

func NewSource 

func NewSource(romFile string, cart Cartridge, elfFile string) (*Source, error)

NewSource is the preferred method of initialisation for the Source type.

If no ELF file or valid DWARF data can be found in relation to the ROM file the function will return nil with an error.

Once the ELF and DWARF file has been identified then Source will always be non-nil but with the understanding that the fields may be empty.

func (*Source) AddFunctionFilter 

func (src *Source) AddFunctionFilter(functionName string)

func (*Source) DropFunctionFilter 

func (src *Source) DropFunctionFilter(functionName string)

DropFunctionFilter drops the existing filter.

func (*Source) FindSourceLine 

func (src *Source) FindSourceLine(addr uint32) *SourceLine

FindSourceLine returns line entry for the address. Returns nil if the address has no source line.

func (*Source) FramebaseCurrent 

func (src *Source) FramebaseCurrent(derivation io.Writer) (uint64, error)

FramebaseCurrent returns the current framebase value

func (*Source) GetLocalVariables 

func (src *Source) GetLocalVariables(ln *SourceLine, addr uint32) []*SourceVariableLocal

GetLocalVariables retuns the list of local variables for the supplied address. Local variables will not be updated.

func (*Source) NewFrame 

func (src *Source) NewFrame(rewinding bool)

NewFrame commits the accumulated profiling for the frame. The rewinding flag indicates that the emulation is in the rewinding state and that some data should not be updated

func (*Source) ResetProfiling added in v0.30.0 

func (src *Source) ResetProfiling()

ResetProfiling resets all profiling information

func (*Source) SourceLineByAddr 

func (src *Source) SourceLineByAddr(addr uint32) *SourceLine

SourceLineByAddr returns the source line for an instruction address. If there is no corresponding source line then a stub is returned.

func (*Source) UpdateGlobalVariables 

func (src *Source) UpdateGlobalVariables()

UpdateGlobalVariables using the current state of the emulated coprocessor. Local variables are updated when coprocessor yields (see OnYield() function)

type SourceFile 

type SourceFile struct {
	Filename      string
	ShortFilename string
	Content       SourceFileContent

	// the source file has at least one global variable if HasGlobals is true
	HasGlobals bool
}

SourceFile is a single source file indentified by the DWARF data.

func (*SourceFile) IsStub 

func (f *SourceFile) IsStub() bool

IsStub returns true if the SourceFile is just a stub.

type SourceFileContent 

type SourceFileContent struct {
	Lines        []*SourceLine
	MaxLineWidth int
}

SourceFileContent lists the lines in a source file

func (SourceFileContent) Len 

func (s SourceFileContent) Len() int

Len implements the fuzzy.Source interface

func (SourceFileContent) String 

func (s SourceFileContent) String(i int) string

String implements the fuzzy.Source interface

type SourceFunction 

type SourceFunction struct {
	// name of function
	Name string

	// range of addresses in which function resides
	Range []SourceRange

	// first source line for each instance of the function. note that the first
	// line of a function may not have any code directly associated with it
	DeclLine *SourceLine

	// profiling for the function
	Cycles           profiling.Cycles
	CumulativeCycles profiling.Cycles
	NumCalls         profiling.Calls
	CyclesPerCall    profiling.CyclesPerCall

	// which 2600 kernel has this function executed in
	Kernel profiling.Focus

	// whether the call stack involving this function is likely inaccurate
	OptimisedCallStack bool
	// contains filtered or unexported fields
}

SourceFunction is a single function identified by the DWARF data or by the ELF symbol table in the case of no DWARF information being available for the function.

func (*SourceFunction) IsInlined 

func (fn *SourceFunction) IsInlined() bool

IsInlined returns true if the function has at least one inlined instance

func (*SourceFunction) IsStub 

func (fn *SourceFunction) IsStub() bool

IsStub returns true if the SourceFunction is just a stub

func (*SourceFunction) String 

func (fn *SourceFunction) String() string

type SourceInstruction 

type SourceInstruction struct {
	// the address in memory of the instruction
	Addr uint32

	// the disassembly entry from the cartridge dissassembly. we don't deal with
	// the details of this type in the coprocessor.developer package
	Disasm coprocessor.CartCoProcDisasmEntry

	// the line of source code this diassembly entry is associated with
	Line *SourceLine
	// contains filtered or unexported fields
}

SourceInstruction is a single intruction from the ELF binary with a reference to a disassembly supplied by the cartridges coprocessor interface.

Not to be confused with anything in the the coprocessor.disassembly package. SourceInstruction instances are intended to be used by static disasemblers.

func (*SourceInstruction) Opcode 

func (d *SourceInstruction) Opcode() string

Opcode returns a string formatted opcode appropriate for the bit length.

func (*SourceInstruction) String 

func (d *SourceInstruction) String() string

type SourceLine 

type SourceLine struct {
	// the actual file/line of the SourceLine. line numbers are counted from one
	File       *SourceFile
	LineNumber int

	// the function the line of source can be found within
	Function *SourceFunction

	// whether this line is to be found inlined elsewhere in the program
	Inlined bool

	// plain string of line
	PlainContent string

	// line divided into parts
	Fragments []SourceLineFragment

	// the list of instructions for this line. will be empty if line is not used
	// in the program (eg. a comment line)
	//
	// note that only instructions for non-inlined ranges will be collated
	Instruction []*SourceInstruction

	// what are the addresses to use for breakpoints
	BreakAddresses []uint32

	// whether this source line has been responsible for a likely bug (eg. illegal access of memory)
	Bug bool

	// profiling for the line
	Cycles profiling.Cycles

	// which 2600 kernel has this line executed in
	Kernel profiling.Focus
}

SourceLine is a single line of source in a source file, identified by the DWARF data and loaded from the actual source file.

func CreateStubLine 

func CreateStubLine(stubFn *SourceFunction) *SourceLine

CreateStubLine returns an instance of SourceLine with the specified SourceFunction assigned to it.

If stubFn is nil then a dummy function will be created.

A stub SourceFile will be created for assignment to the SourceLine.File field.

func (*SourceLine) IsStub 

func (ln *SourceLine) IsStub() bool

IsStub returns true if the SourceLine is just a stub.

func (*SourceLine) String 

func (ln *SourceLine) String() string

type SourceLineFragment 

type SourceLineFragment struct {
	Type    SourceLineFragmentType
	Content string
}

SourceLineFragment represents an single part of the entire source line.

type SourceLineFragmentType 

type SourceLineFragmentType int

SourceLineFragmentType defines how a single SourceLineFragment should be interpretted. 

const (
	FragmentCode SourceLineFragmentType = iota
	FragmentComment
	FragmentStringLiteral
)

A list of the valid SourceLineFragmentTypes.

type SourceRange 

type SourceRange struct {
	Start  uint64
	End    uint64
	Inline bool
}

SourceRange is used to specify the effective start and end addresses of a function or a variable.

func (SourceRange) InRange 

func (r SourceRange) InRange(addr uint64) bool

InRange returns true if address is in range of start and end addresses

func (SourceRange) Size 

func (r SourceRange) Size() uint64

Size returns the size of the range

func (SourceRange) String 

func (r SourceRange) String() string

String returns the start/end addresses of the range. If the range is inlined then the addresses are printed with square brackets.

type SourceType 

type SourceType struct {
	Name string

	// is a constant type
	Constant bool

	// the base type of pointer types. will be nil if type is not a pointer type
	PointerType *SourceType

	// size of values of this type (in bytes)
	Size int

	// empty if type is not a composite type. see SourceVariable.IsComposite() function
	Members []*SourceVariable

	// number of elements in the type. if count is more than zero then this
	// type is an array. see SourceVariable.IsArry() function
	ElementCount int

	// the base type of all the elements in the type
	ElementType *SourceType

	// whether to allow type level conversion of the type
	Conversion func(v uint32) (string, any)
}

SourceType is a single type identified by the DWARF data. Composite types are differentiated by the existance of member fields

func (*SourceType) Bin 

func (typ *SourceType) Bin() string

Bin returns a format string to represent a value as a correctly padded binary number.

func (*SourceType) Hex 

func (typ *SourceType) Hex() string

Hex returns a format string to represent a value as a correctly padded hexadecinal number.

func (*SourceType) IsArray 

func (typ *SourceType) IsArray() bool

IsArray returns true if SourceType is an array type.

func (*SourceType) IsComposite 

func (typ *SourceType) IsComposite() bool

IsComposite returns true if SourceType is a composite type.

func (*SourceType) IsPointer 

func (typ *SourceType) IsPointer() bool

IsPointer returns true if SourceType is a pointer type.

func (*SourceType) Mask 

func (typ *SourceType) Mask() uint32

Mask returns the mask value of the correct size for the type.

func (*SourceType) String 

func (typ *SourceType) String() string

type SourceVariable 

type SourceVariable struct {
	// name of variable
	Name string

	// variable type (int, char, etc.)
	Type *SourceType

	// first source line for each instance of the function
	DeclLine *SourceLine

	// if Error is not nil then an error was enountered during a resolve()
	// sequence. the error will be logged when the field is first set to true
	Error error
	// contains filtered or unexported fields
}

SourceVariable is a single variable identified by the DWARF data.

func (*SourceVariable) Address 

func (varb *SourceVariable) Address() (uint64, bool)

Address returns the location in memory of the variable referred to by SourceVariable

func (*SourceVariable) Child 

func (varb *SourceVariable) Child(i int) *SourceVariable

Child returns the i'th child of the variable. A child can be an array element, composite member or dereferenced variable, as appropriate for the variables SourceType

Count from zero. Returns nil if no such child exists

func (*SourceVariable) IsValid 

func (varb *SourceVariable) IsValid() bool

IsValid returns true if the variable has a valid or resolvable value

func (*SourceVariable) NumChildren 

func (varb *SourceVariable) NumChildren() int

NumChildren returns the number of children for this variable

func (*SourceVariable) String 

func (varb *SourceVariable) String() string

func (*SourceVariable) Update 

func (varb *SourceVariable) Update()

Update variable. It should be called periodically before using the return value from Address() or Value()

Be careful to only call this from the emulation goroutine.

func (*SourceVariable) Value 

func (varb *SourceVariable) Value() uint32

Value returns the current value of a SourceVariable

func (*SourceVariable) WriteDerivation 

func (varb *SourceVariable) WriteDerivation(w io.Writer) error

WriteDerivation outputs the derivation of a varibale to the io.Writer. If the derivation encounters an error the error is returned

Note that the basic information about the variable is not output by this function. The String() function provides that information

type SourceVariableLocal 

type SourceVariableLocal struct {
	*SourceVariable

	// the address range for which the variable is valid
	Range SourceRange
}

SourceVariableLocal represents a single local variable identified by the DWARF data.

Source Files

View all Source files

Directories

Path Synopsis
Package leb128 implements the Variable Length Data encoding method as required by the DWARF debugging format.
 Package leb128 implements the Variable Length Data encoding method as required by the DWARF debugging format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.