developer

package
v0.19.3 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2022 License: GPL-3.0, GPL-3.0 Imports: 18 Imported by: 0

Documentation

Overview

Package developer offers additional functionality to the developer of ROMs that use a coprocessor. It uses available DWARF data for a binary in order to provide the developer performance profiling and variable information.

The functionality of this package will be greatly expanded in the future.

Index

Constants

View Source 
const (
	UnknownFunction   = "<unknown function>"
	UnknownSourceLine = "<unknown source line>"
)

Strings used to indicate unknown values.

Variables

View Source 
var AvailableInKernelOptions = []string{"Any", "VBLANK", "Screen", "Overscan", "ROM Setup"}

List of KernelVCS values as strings

Functions

This section is empty.

Types

type CallStack added in v0.19.3 

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

CallStack maintains information about function calls and the order in which they happen.

func (*CallStack) String added in v0.19.3 

func (cs *CallStack) String() string

type Developer 

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

Developer implements the CartCoProcDeveloper interface.

func NewDeveloper 

func NewDeveloper(romFile string, cart mapper.CartCoProc, tv TV, elfFile string) *Developer

NewDeveloper is the preferred method of initialisation for the Developer type.

func (*Developer) BorrowIllegalAccess 

func (dev *Developer) BorrowIllegalAccess(f func(*IllegalAccess))

BorrowIllegalAccess will lock the illegal access log for the duration of the supplied fucntion, which will be executed with the illegal access log as an argument.

func (*Developer) BorrowSource 

func (dev *Developer) BorrowSource(f func(*Source))

BorrowSource will lock the source code structure for the durction of the supplied function, which will be executed with the source code structure as an argument.

May return nil.

func (*Developer) CheckBreakpoint added in v0.19.3 

func (dev *Developer) CheckBreakpoint(addr uint32) bool

CheckBreakpoint implements the mapper.CartCoProcDeveloper interface.

func (*Developer) Disable added in v0.19.1 

func (dev *Developer) Disable(disable bool)

Enable or disable the CartCoProcDeveloper interface.

func (*Developer) HasSource 

func (dev *Developer) HasSource() bool

HasSource returns true if source information has been found.

func (*Developer) IllegalAccess 

func (dev *Developer) IllegalAccess(event string, pc uint32, addr uint32) string

IllegalAccess implements the CartCoProcDeveloper interface.

func (*Developer) NewFrame 

func (dev *Developer) NewFrame(frameInfo television.FrameInfo) error

NewFrame implements the television.FrameTrigger interface.

func (*Developer) NullAccess added in v0.18.0 

func (dev *Developer) NullAccess(event string, pc uint32, addr uint32) string

IllegalAccess implements the CartCoProcDeveloper interface.

func (*Developer) ProcessProfiling added in v0.19.3 

func (dev *Developer) ProcessProfiling()

ProcessProfiling implements the mapper.CartCoProcDeveloper interface.

func (*Developer) Profiling added in v0.19.3 

func (dev *Developer) Profiling() *mapper.CartCoProcProfiler

Profiling implements the mapper.CartCoProcDeveloper interface.

func (*Developer) ResetStatistics added in v0.19.3 

func (dev *Developer) ResetStatistics()

ResetStatistics resets all performance statistics. This differs from the function in the Source type in that it acquires and releases the source critical section.

func (*Developer) StackCollision added in v0.18.0 

func (dev *Developer) StackCollision(pc uint32, addr uint32) string

IllegalAccess implements the CartCoProcDeveloper interface.

func (*Developer) StartProfiling added in v0.19.3 

func (dev *Developer) StartProfiling()

StartProfiling implements the mapper.CartCoProcDeveloper interface.

func (*Developer) VariableMemtop added in v0.18.0 

func (dev *Developer) VariableMemtop() uint32

VariableMemtop implements the CartCoProcDeveloper interface.

type DisasmRange added in v0.17.0 

type DisasmRange struct {
	Disasm []*SourceDisasm
}

DisasmRange is used to dynamically create a list of SourceDisasm entries.

func (*DisasmRange) Add added in v0.17.0 

func (rng *DisasmRange) Add(line *SourceLine)

Add the disassembly entries for a SourceLine to the range.

func (*DisasmRange) Clear added in v0.17.0 

func (rng *DisasmRange) Clear()

Clear all disassembly entires from the range.

func (*DisasmRange) IsEmpty added in v0.17.0 

func (rng *DisasmRange) IsEmpty() bool

IsEmpty returns true if there are now SourceDisasm entries in the range.

func (*DisasmRange) Len added in v0.17.0 

func (rng *DisasmRange) Len() int

Len implements the sort.Sort interface.

func (*DisasmRange) Less added in v0.17.0 

func (rng *DisasmRange) Less(i int, j int) bool

Less implements the sort.Sort interface.

func (*DisasmRange) Swap added in v0.17.0 

func (rng *DisasmRange) Swap(i int, j int)

Swap implements the sort.Sort interface.

type FunctionFilter added in v0.17.0 

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

type IllegalAccess 

type IllegalAccess struct {

	// all the accesses in order of the first time they appear. the Count field
	// in the IllegalAccessEntry can be used to see if that entry was seen more
	// than once *after* the first appearance
	Log []*IllegalAccessEntry

	// is true once a stack collision has been detected. once a stack collision
	// has occured then subsequent illegal accesses cannot be trusted and will
	// likely not be logged
	HasStackCollision bool
	// contains filtered or unexported fields
}

IllegalAccess records memory accesses by the coprocesser that are "illegal".

type IllegalAccessEntry 

type IllegalAccessEntry struct {
	Event      string
	PC         uint32
	AccessAddr uint32

	SrcLine *SourceLine
	Count   int

	// whether access address was reported as being a "null access". when this
	// is true the illegal access is very likely because of a null pointer
	// dereference
	IsNullAccess bool
}

IllegalAccessEntry is a single entry in the illegal access log.

type KernelVCS added in v0.19.3 

type KernelVCS int

KernelVCS indicates the 2600 kernel that is associated with a source function or source line. 

const (
	KernelAny      KernelVCS = 0x00
	KernelScreen   KernelVCS = 0x01
	KernelVBLANK   KernelVCS = 0x02
	KernelOverscan KernelVCS = 0x04

	// code that is run while the television is in an unstable state
	KernelUnstable KernelVCS = 0x08
)

List of KernelVCS values.

func (KernelVCS) String added in v0.19.3 

func (k KernelVCS) String() string

type Load added in v0.17.0 

type Load struct {
	// cycle count
	FrameCount   float32
	AverageCount float32
	MaxCount     float32

	// cycle count expressed as a percentage
	Frame   float32
	Average float32
	Max     float32

	// whether the corresponding values are valid
	FrameValid   bool
	AverageValid bool
	MaxValid     bool
}

Load records the frame (or current) load as well as the average and maximum load.

type SortedFunctions added in v0.17.0 

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

func (SortedFunctions) Len added in v0.17.0 

func (e SortedFunctions) Len() int

func (SortedFunctions) Less added in v0.17.0 

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

func (*SortedFunctions) SetCumulative added in v0.19.3 

func (e *SortedFunctions) SetCumulative(set bool)

func (*SortedFunctions) SetKernel added in v0.18.0 

func (e *SortedFunctions) SetKernel(kernel KernelVCS)

func (SortedFunctions) Sort added in v0.17.0 

func (e SortedFunctions) Sort()

func (*SortedFunctions) SortByAverageCycles added in v0.17.0 

func (e *SortedFunctions) SortByAverageCycles(descending bool)

func (*SortedFunctions) SortByFile added in v0.17.0 

func (e *SortedFunctions) SortByFile(descending bool)

func (*SortedFunctions) SortByFrameCycles added in v0.17.0 

func (e *SortedFunctions) SortByFrameCycles(descending bool)

func (*SortedFunctions) SortByFunction added in v0.17.0 

func (e *SortedFunctions) SortByFunction(descending bool)

func (*SortedFunctions) SortByMaxCycles added in v0.17.0 

func (e *SortedFunctions) SortByMaxCycles(descending bool)

func (SortedFunctions) Swap added in v0.17.0 

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

func (*SortedFunctions) UseRawCyclesCounts added in v0.19.3 

func (e *SortedFunctions) UseRawCyclesCounts(use bool)

type SortedLines added in v0.17.0 

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

func (SortedLines) Len added in v0.17.0 

func (e SortedLines) Len() int

func (SortedLines) Less added in v0.17.0 

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

func (*SortedLines) SetKernel added in v0.18.0 

func (e *SortedLines) SetKernel(kernel KernelVCS)

func (SortedLines) Sort added in v0.17.0 

func (e SortedLines) Sort()

func (*SortedLines) SortByAverageLoadOverFunction added in v0.17.0 

func (e *SortedLines) SortByAverageLoadOverFunction(descending bool)

func (*SortedLines) SortByAverageLoadOverSource added in v0.17.0 

func (e *SortedLines) SortByAverageLoadOverSource(descending bool)

func (*SortedLines) SortByFile added in v0.17.0 

func (e *SortedLines) SortByFile(descending bool)

func (*SortedLines) SortByFrameLoadOverFunction added in v0.17.0 

func (e *SortedLines) SortByFrameLoadOverFunction(descending bool)

func (*SortedLines) SortByFrameLoadOverSource added in v0.17.0 

func (e *SortedLines) SortByFrameLoadOverSource(descending bool)

func (*SortedLines) SortByFunction added in v0.17.0 

func (e *SortedLines) SortByFunction(descending bool)

func (*SortedLines) SortByLineAndFunction added in v0.17.0 

func (e *SortedLines) SortByLineAndFunction(descending bool)

func (*SortedLines) SortByLineNumber added in v0.17.0 

func (e *SortedLines) SortByLineNumber(descending bool)

func (*SortedLines) SortByMaxLoadOverFunction added in v0.17.0 

func (e *SortedLines) SortByMaxLoadOverFunction(descending bool)

func (*SortedLines) SortByMaxLoadOverSource added in v0.17.0 

func (e *SortedLines) SortByMaxLoadOverSource(descending bool)

func (SortedLines) Swap added in v0.17.0 

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

func (*SortedLines) UseRawCyclesCounts added in v0.19.3 

func (e *SortedLines) UseRawCyclesCounts(use bool)

type SortedVariableMethod added in v0.18.0 

type SortedVariableMethod int
const (
	SortVariableByName SortedVariableMethod = iota
	SortVariableByAddress
)

type SortedVariables added in v0.18.0 

type SortedVariables struct {
	Variables  []*SourceVariable
	Method     SortedVariableMethod
	Descending bool
}

func (SortedVariables) Len added in v0.18.0 

func (v SortedVariables) Len() int

func (SortedVariables) Less added in v0.18.0 

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

func (*SortedVariables) SortByAddress added in v0.18.0 

func (e *SortedVariables) SortByAddress(descending bool)

func (*SortedVariables) SortByName added in v0.18.0 

func (e *SortedVariables) SortByName(descending bool)

func (SortedVariables) Swap added in v0.18.0 

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

type Source 

type Source struct {

	// source is compiled with optimisation
	Optimised bool

	// disassembled binary
	Disassembly map[uint64]*SourceDisasm

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

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

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

	// types used in the source
	Types map[dwarf.Offset]*SourceType

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

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

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

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

	// statistics for the entire program
	Stats StatsGroup

	// 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 statistics for only one reason
	ExecutionProfileChanged bool

	// list of breakpoints on ARM program
	Breakpoints map[uint32]bool

	// call stack of running program
	CallStack CallStack
	// 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 added in v0.17.0 

func NewSource(romFile string, cart mapper.CartCoProc, 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) AddBreakpoint added in v0.19.3 

func (src *Source) AddBreakpoint(addr uint32)

AddBreakpoint adds an address to the list of addresses that will be checked each PC iteration.

func (*Source) AddFunctionFilter added in v0.17.0 

func (src *Source) AddFunctionFilter(functionName string)

func (*Source) CheckBreakpoint added in v0.19.3 

func (src *Source) CheckBreakpoint(addr uint32) bool

CheckBreakpoint compares an address to the list of breakpoints.

func (*Source) DropFunctionFilter added in v0.17.0 

func (src *Source) DropFunctionFilter(functionName string)

DropFunctionFilter drops the existing filter.

func (*Source) FindSourceLine added in v0.19.3 

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) RemoveBreakpoint added in v0.19.3 

func (src *Source) RemoveBreakpoint(addr uint32)

AddBreakpoint removes an address from the list of breakpoint addresses.

func (*Source) ResetStatistics added in v0.18.0 

func (src *Source) ResetStatistics()

ResetStatistics resets all performance statistics.

func (*Source) ToggleBreakpoint added in v0.19.3 

func (src *Source) ToggleBreakpoint(addr uint32)

ToggleBreakpoint adds or removes a breakpoint depending on whether the breakpoint already exists.

type SourceDisasm added in v0.17.0 

type SourceDisasm struct {
	Addr        uint32
	Opcode      uint16
	Instruction string

	Line *SourceLine
}

SourceDisasm is a single disassembled intruction from the ELF binary. Not to be confused with the coprocessor.disassembly package. SourceDisasm instances are intended to be used by static disasemblers.

func (*SourceDisasm) String added in v0.17.0 

func (d *SourceDisasm) String() string

type SourceFile added in v0.17.0 

type SourceFile struct {
	Filename      string
	ShortFilename string
	Lines         []*SourceLine

	// 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.

type SourceFunction added in v0.17.0 

type SourceFunction struct {
	Name string

	// 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.
	// the Disassembly and Stats fields therefore should not be relied upon.
	DeclLine *SourceLine

	// stats for the function
	FlatStats       StatsGroup
	CumulativeStats StatsGroup

	// which 2600 kernel has this function executed in
	Kernel KernelVCS

	// whether the call stack involving this function is likely inaccurate
	OptimisedCallStack bool
}

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.

Use NoSource() to detect if function has no DWARF information.

func (*SourceFunction) IsStub added in v0.19.3 

func (fn *SourceFunction) IsStub() bool

IsStub returns true if thre is no DWARF data for this function.

type SourceLine added in v0.17.0 

type SourceLine struct {
	// the actual file/line of the SourceLine
	File       *SourceFile
	LineNumber int

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

	// plain string of line
	PlainContent string

	// line divided into parts
	Fragments []SourceLineFragment

	// the generated assembly for this line. will be empty if line is a comment or otherwise unsused
	Disassembly []*SourceDisasm

	// some source lines will interleave their coproc instructions
	// (disassembly) with other source lines
	Interleaved bool

	// whether this source line has been responsible for an illegal access of memory
	IllegalAccess bool

	// statistics for the line
	Stats StatsGroup

	// which 2600 kernel has this line executed in
	Kernel KernelVCS
}

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

func (*SourceLine) IsStub added in v0.19.3 

func (ln *SourceLine) IsStub() bool

IsStub returns true if thre is no DWARF data for this function.

func (*SourceLine) String added in v0.17.0 

func (ln *SourceLine) String() string

type SourceLineFragment added in v0.17.0 

type SourceLineFragment struct {
	Type    SourceLineFragmentType
	Content string
}

SourceLineFragment represents an single part of the entire source line.

type SourceLineFragmentType added in v0.17.0 

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 SourceType added in v0.18.0 

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
}

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

func (*SourceType) Bin added in v0.18.0 

func (typ *SourceType) Bin() string

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

func (*SourceType) Hex added in v0.18.0 

func (typ *SourceType) Hex() string

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

func (*SourceType) IsArray added in v0.18.0 

func (typ *SourceType) IsArray() bool

IsArray returns true if SourceType is an array type.

func (*SourceType) IsComposite added in v0.18.0 

func (typ *SourceType) IsComposite() bool

IsComposite returns true if SourceType is a composite type.

func (*SourceType) IsPointer added in v0.18.0 

func (typ *SourceType) IsPointer() bool

IsPointer returns true if SourceType is a pointer type.

func (*SourceType) Mask added in v0.18.0 

func (typ *SourceType) Mask() uint32

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

type SourceVariable added in v0.18.0 

type SourceVariable struct {
	Name string

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

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

	// address in memory of the variable. if the variable is a member of
	// another type then the Address is an offset from the address of the
	// parent variable
	Address uint64
	// contains filtered or unexported fields
}

SourceVariable is a single variable identified by the DWARF data.

func (*SourceVariable) AddressIsOffset added in v0.18.0 

func (varb *SourceVariable) AddressIsOffset() bool

AddressIsOffset returns true if SourceVariable is member of another type

func (*SourceVariable) IsArray added in v0.18.0 

func (varb *SourceVariable) IsArray() bool

IsArray returns true if SourceVariables of an array type.

func (*SourceVariable) IsComposite added in v0.18.0 

func (varb *SourceVariable) IsComposite() bool

IsComposite returns true if SourceVariable is of a composite type.

func (*SourceVariable) IsPointer added in v0.18.0 

func (varb *SourceVariable) IsPointer() bool

IsPointer returns true if SourceVariables is a pointer type.

func (*SourceVariable) String added in v0.18.0 

func (varb *SourceVariable) String() string

type Stats added in v0.17.0 

type Stats struct {
	OverSource   Load
	OverFunction Load
	// contains filtered or unexported fields
}

Stats records the cycle count over time and can be used to the frame (or current) load as well as average and maximum load.

The actual percentage values are accessed through the OverSource and OverFunction fields. These fields provide the necessary scale by which the load is measured.

The validity of the OverSource and OverFunction fields depends on context. For instance, for the SourceFunction type, the corresponding OverFunction field is invalid. For the Source type meanwhile, neither field is valid.

For the SourceLine type however, both OverSource and OverFunction can be used to provide a different scaling to the load values.

func (*Stats) IsValid added in v0.17.0 

func (stats *Stats) IsValid() bool

IsValid returns true if the statistics have ever been updated. ie. the source associated with this statistic has ever executed.

type StatsGroup added in v0.19.3 

type StatsGroup struct {
	// cycle statistics for the entire program
	Overall Stats

	// kernel specific cycle statistics for the program. accumulated only once TV is stable
	VBLANK   Stats
	Screen   Stats
	Overscan Stats
	ROMSetup Stats
}

StatsGroup collates the Stats instance for all kernel views of the program.

type TV added in v0.18.0 

type TV interface {
	GetFrameInfo() television.FrameInfo
	GetCoords() coords.TelevisionCoords
}

TV is the interface from the developer type to the television implementation.

Source Files

View all Source files

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.