Documentation ¶
Overview ¶
Package developer offers additional functionality to the developer of ROMs that use a coprocessor. For instance, it handles the loading of .map and .obj files if they have been generated during the compilation of the 2600 ROM. The .map and .obj files are used to provide source code level information during execution.
Objdump type is a very basic parser for obj files as produced by "objdump -S" on the base elf file that is used to create a cartridge binary
Index ¶
- Constants
- Variables
- type Developer
- func (dev *Developer) BorrowFrameStats(f func(*FrameStats))
- func (dev *Developer) BorrowIllegalAccess(f func(*IllegalAccess))
- func (dev *Developer) BorrowSource(f func(*Source))
- func (dev *Developer) ExecutionEnd()
- func (dev *Developer) ExecutionProfile(addr map[uint32]float32)
- func (dev *Developer) ExecutionStart()
- func (dev *Developer) HasSource() bool
- func (dev *Developer) IllegalAccess(event string, pc uint32, addr uint32) string
- func (dev *Developer) NewFrame(frameInfo television.FrameInfo) error
- func (dev *Developer) NullAccess(event string, pc uint32, addr uint32) string
- func (dev *Developer) StackCollision(pc uint32, addr uint32) string
- func (dev *Developer) VariableMemtop() uint32
- type DisasmRange
- type FrameSegmentStats
- type FrameStats
- type FunctionFilter
- type IllegalAccess
- type IllegalAccessEntry
- type InKernel
- type Load
- type SortedFunctions
- func (e SortedFunctions) Len() int
- func (e SortedFunctions) Less(i int, j int) bool
- func (e *SortedFunctions) SetKernel(kernel InKernel)
- func (e SortedFunctions) Sort()
- func (e *SortedFunctions) SortByAverageCycles(descending bool)
- func (e *SortedFunctions) SortByFile(descending bool)
- func (e *SortedFunctions) SortByFrameCycles(descending bool)
- func (e *SortedFunctions) SortByFunction(descending bool)
- func (e *SortedFunctions) SortByMaxCycles(descending bool)
- func (e SortedFunctions) Swap(i int, j int)
- type SortedLines
- func (e SortedLines) Len() int
- func (e SortedLines) Less(i int, j int) bool
- func (e *SortedLines) SetKernel(kernel InKernel)
- func (e SortedLines) Sort()
- func (e *SortedLines) SortByAverageLoadOverFunction(descending bool)
- func (e *SortedLines) SortByAverageLoadOverSource(descending bool)
- func (e *SortedLines) SortByFile(descending bool)
- func (e *SortedLines) SortByFrameLoadOverFunction(descending bool)
- func (e *SortedLines) SortByFrameLoadOverSource(descending bool)
- func (e *SortedLines) SortByFunction(descending bool)
- func (e *SortedLines) SortByLineAndFunction(descending bool)
- func (e *SortedLines) SortByLineNumber(descending bool)
- func (e *SortedLines) SortByMaxLoadOverFunction(descending bool)
- func (e *SortedLines) SortByMaxLoadOverSource(descending bool)
- func (e SortedLines) Swap(i int, j int)
- type SortedVariableMethod
- type SortedVariables
- type Source
- type SourceDisasm
- type SourceFile
- type SourceFunction
- type SourceLine
- type SourceLineFragment
- type SourceLineFragmentType
- type SourceType
- type SourceVariable
- type Stats
- type TV
Constants ¶
const ( UnknownFunction = "<unknown function>" UnknownSourceLine = "<unknown source line>" )
Strings used to indicate unknown values.
Variables ¶
var AvailableInKernelOptions = []string{"All", "VBLANK", "Screen", "Overscan", "ROM Setup"}
List of InKernelValues as strings
Functions ¶
This section is empty.
Types ¶
type Developer ¶
type Developer struct {
// contains filtered or unexported fields
}
Developer implements the CartCoProcDeveloper interface.
func NewDeveloper ¶
func NewDeveloper(pathToROM string, cart mapper.CartCoProcBus, tv TV) *Developer
NewDeveloper is the preferred method of initialisation for the Developer type.
func (*Developer) BorrowFrameStats ¶ added in v0.18.0
func (dev *Developer) BorrowFrameStats(f func(*FrameStats))
BorrowFrameStats will lock the frame statistics for the duration of the supplied function, which will be executed with the developer's frame statistics argument.
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 ¶
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) ExecutionEnd ¶ added in v0.18.0
func (dev *Developer) ExecutionEnd()
ExecutionEnd implements the CartCoProcDeveloper interface.
func (*Developer) ExecutionProfile ¶
xecutionProfile implements the CartCoProcDeveloper interface.
func (*Developer) ExecutionStart ¶ added in v0.18.0
func (dev *Developer) ExecutionStart()
ExecutionStart implements the CartCoProcDeveloper interface.
func (*Developer) IllegalAccess ¶
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
IllegalAccess implements the CartCoProcDeveloper interface.
func (*Developer) StackCollision ¶ added in v0.18.0
IllegalAccess implements the CartCoProcDeveloper interface.
func (*Developer) VariableMemtop ¶ added in v0.18.0
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 FrameSegmentStats ¶ added in v0.18.0
type FrameSegmentStats struct { // counts expressed as VCS clocks ClocksCount float32 AverageCount float32 MaxCount float32 // counts expressed as percentages Clocks float32 Average float32 Max float32 // contains filtered or unexported fields }
func (*FrameSegmentStats) HasRun ¶ added in v0.18.0
func (seg *FrameSegmentStats) HasRun() bool
HasRun returns false if no coprocessor activity has been seen in the segment
type FrameStats ¶ added in v0.18.0
type FrameStats struct { FrameInfo television.FrameInfo Frame FrameSegmentStats VBLANK FrameSegmentStats Screen FrameSegmentStats Overscan FrameSegmentStats // contains filtered or unexported fields }
FrameStats measures coprocessor performance against the TV frame.
InKernel value of InROMSetup is not tracked by the FrameStats struct.
func (*FrameStats) Reset ¶ added in v0.18.0
func (stats *FrameStats) Reset()
Reset frame statistics.
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 InKernel ¶ added in v0.18.0
type InKernel int
InKernel indicates the 2600 kernel that is associated with a source function or source line.
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) SetKernel ¶ added in v0.18.0
func (e *SortedFunctions) SetKernel(kernel InKernel)
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)
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) SetKernel ¶ added in v0.18.0
func (e *SortedLines) SetKernel(kernel InKernel)
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)
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) 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 { // if any of the compile units were compiled with GCC optimisation then // this string will contain an appropriate message. if string is empty then // the detected optimisation was acceptable (or there is no optimisation or // the compiler is unsupported) // // a GCC optimisation of -Os is okay // // optimisation can cause misleading or confusing information (albeit still // technically correct in terms of performance analysis) UnsupportedOptimisation string // 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 // list of funcions sorted by FrameCycles field 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 // list of source lines sorted by FrameCycles field SortedLines SortedLines // sorted lines filtered by function name FunctionFilters []*FunctionFilter // cycle statisics for the entire program Stats Stats // kernel specific cycle statistics for the program. accumulated only once TV is stable StatsVBLANK Stats StatsScreen Stats StatsOverscan Stats StatsROMSetup Stats // 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 // 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
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 pathToROM argument, 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 ¶ added in v0.17.0
func (*Source) DropFunctionFilter ¶ added in v0.17.0
DropFunctionFilter drops the existing filter.
func (*Source) ResetStatistics ¶ added in v0.18.0
func (src *Source) ResetStatistics()
ResetStatistics resets all performance statistics.
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.
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 DeclLine *SourceLine // cycle statisics for the function Stats Stats // kernel specific cycle statistics for the function. accumulated only once TV is stable StatsVBLANK Stats StatsScreen Stats StatsOverscan Stats StatsROMSetup Stats // which 2600 kernel has this function executed in Kernel InKernel }
SourceFunction is a single function identified by the DWARF data.
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 // cycle statisics for the line Stats Stats // kernel specific cycle statistics for the line. accumulated only once TV is stable StatsVBLANK Stats StatsScreen Stats StatsOverscan Stats StatsROMSetup Stats // which 2600 kernel has this line executed in Kernel InKernel }
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) 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 // 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
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.
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.