developer

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: May 30, 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. 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

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

Strings used to indicate unknown values.

Variables

View Source 
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 

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

func (dev *Developer) ExecutionEnd()

ExecutionEnd implements the CartCoProcDeveloper interface.

func (*Developer) ExecutionProfile 

func (dev *Developer) ExecutionProfile(addr map[uint32]float32)

xecutionProfile implements the CartCoProcDeveloper interface.

func (*Developer) ExecutionStart added in v0.18.0 

func (dev *Developer) ExecutionStart()

ExecutionStart implements 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) StackCollision added in v0.18.0 

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

IllegalAccess implements the 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 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. 

const (
	InKernelAll InKernel = 0x00
	InScreen    InKernel = 0x01
	InVBLANK    InKernel = 0x02
	InOverscan  InKernel = 0x04
	InROMSetup  InKernel = 0x08
)

List of InKernel values.

func (InKernel) String added in v0.18.0 

func (k InKernel) 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) 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) 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 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) 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 {

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

func NewSource(pathToROM 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 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 (src *Source) AddFunctionFilter(functionName string)

func (*Source) DropFunctionFilter added in v0.17.0 

func (src *Source) DropFunctionFilter(functionName string)

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 

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