coprocessor

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: 3 Imported by: 0

Documentation

Overview

Package coprocessor contains the helper functions for cartridge coprocessors. In practice this means the ARM processor but we'll try to keep it general in case of future developments in the 2600 scene.

The two subpackages, developer and disassembly, are distinct. The reason for the distinction is this: the developer package will only be used if the development files for the emulated ROM can be found. The disassembly package meanwhile, will work with any ROM and will endeavour to provide an accurate disassembly of the running coprocessor program.

Index

Constants

View Source 
const ExtendedRegisterCoreGroup = "Core"

The basic set of registers present in a coprocessor. Every implementation should specify this group at a minimum

Variables

This section is empty.

Functions

This section is empty.

Types

type CartCoProc 

type CartCoProc interface {
	ProcessorID() string

	// set disassembler and developer hooks
	SetDisassembler(CartCoProcDisassembler)
	SetDeveloper(CartCoProcDeveloper)

	// breakpoint control of coprocessor
	BreakpointsEnable(bool)

	// RegisterSpec returns the specification for the registers visible in the
	// coprocessor. Implementations should ensure that these conform to the
	// DWARF extended register specification for the processor type (if
	// avaiable)
	//
	// Additional registers not required by the DWARF specification may be
	// supported as required
	//
	// Implementations should include the ExtendedRegisterCoreGroup at a minimum
	RegisterSpec() ExtendedRegisterSpec

	// the contents of a register. the implementation should support extended
	// register values defined by DWARF for the coprocessor
	//
	// if the register is unrecognised or unsupported the function will return
	// false
	Register(register int) (uint32, bool)

	// the contents of the register and a formatted string appropriate for the
	// register type
	RegisterFormatted(register int) (uint32, string, bool)

	// as above but setting the value of the register
	RegisterSet(register int, value uint32) bool

	// returns the current stack frame
	StackFrame() uint32

	// read coprocessor memory address for 32bit value. return false if address is out of range
	Peek(addr uint32) (uint32, bool)
}

CartCoProc is implemented by processors that are used in VCS cartridges. Principally this means ARM type processors but other processor types may be possible.

type CartCoProcBus 

type CartCoProcBus interface {
	// return the actual coprocessor interface. if the cartridge implements the
	// CartCoProcBus then it should always return a non-nil CartCoProc instance
	GetCoProc() CartCoProc

	// set interface for cartridge yields
	SetYieldHook(CartYieldHook)

	// the state of the coprocessor
	CoProcExecutionState() CoProcExecutionState
}

CartCoProcBus is implemented by cartridge mappers that have a coprocessor

type CartCoProcDeveloper 

type CartCoProcDeveloper interface {
	// a memory fault has occured
	MemoryFault(event string, explanation faults.Category, instructionAddr uint32, accessAddr uint32)

	// returns the highest address used by the program. the coprocessor uses
	// this value to detect stack collisions
	HighAddress() uint32

	// checks if address has a breakpoint assigned to it
	CheckBreakpoint(addr uint32) bool

	// returns a map that can be used to count cycles for each PC address
	Profiling() *CartCoProcProfiler

	// notifies developer that the start of a new profiling session is about to begin
	StartProfiling()

	// instructs developer implementation to accumulate profiling data. there
	// can be many calls to profiling profiling for every call to start
	// profiling
	ProcessProfiling()

	// called whenever the ARM yields to the VCS. it communicates the PC of the
	// most recent instruction, the current PC (as it is now), and the reason
	// for the yield
	OnYield(currentPC uint32, reason CoProcYield)
}

CartCoProcDeveloper is implemented by a coprocessor to provide functions available to developers when the source code is available.

type CartCoProcDisasmEntry 

type CartCoProcDisasmEntry interface {
	String() string
	Key() string
	CSV() string
	Size() int
}

CartCoProcDisasmEntry represents a single decoded instruction by the coprocessor.

type CartCoProcDisasmSummary 

type CartCoProcDisasmSummary interface {
	String() string
}

CartCoProcDisasmSummary represents a summary of a coprocessor execution.

type CartCoProcDisassembler 

type CartCoProcDisassembler interface {
	// Start is called at the beginning of coprocessor program execution.
	Start()

	// Step called after every instruction in the coprocessor program.
	Step(CartCoProcDisasmEntry)

	// End is called when coprocessor program has finished.
	End(CartCoProcDisasmSummary)
}

CartCoProcDisassembler defines the functions that must be defined for a disassembler to be attached to a coprocessor.

type CartCoProcDisassemblerStdout 

type CartCoProcDisassemblerStdout struct {
}

CartCoProcDisassemblerStdout is a minimial implementation of the CartCoProcDisassembler interface. It outputs entries to stdout immediately upon request.

func (*CartCoProcDisassemblerStdout) End 

func (c *CartCoProcDisassemblerStdout) End(s CartCoProcDisasmSummary)

End implements the CartCoProcDisassembler interface.

func (*CartCoProcDisassemblerStdout) Start 

func (c *CartCoProcDisassemblerStdout) Start()

Start implements the CartCoProcDisassembler interface.

func (*CartCoProcDisassemblerStdout) Step 

func (c *CartCoProcDisassemblerStdout) Step(e CartCoProcDisasmEntry)

Instruction implements the CartCoProcDisassembler interface.

type CartCoProcOrigin added in v0.30.0 

type CartCoProcOrigin interface {
	ExecutableOrigin() uint32
}

CartCoProcOrigin is implemented by cartridge mappers where coprocessor programs are located at a specific address

type CartCoProcProfileEntry 

type CartCoProcProfileEntry struct {
	Addr   uint32
	Cycles float32
}

CartCoProcProfileEntry indicates the number of coprocessor cycles used by the instruction at the specified adress

type CartCoProcProfiler 

type CartCoProcProfiler struct {
	Entries []CartCoProcProfileEntry
}

CartCoProcProfiler is shared by CartCoProcDeveloper and used by a coprocessor to record profiling information

type CartCoProcRelocatable 

type CartCoProcRelocatable interface {
	// returns the offset of the named ELF section and whether the named
	// section exists. not all cartridges that implement this interface will be
	// able to meaningfully answer this function call
	ELFSection(string) ([]uint8, uint32, bool)
}

CartCoProcRelocatable is implemented by cartridge mappers where coprocessor programs can be located anywhere in the coprcessor's memory

type CartYieldHook 

type CartYieldHook interface {
	CartYield(CoProcYieldType) YieldHookResponse
}

CartYieldHook allows a cartridge to halt execution if the cartridge coprocessor has reached a breakpoint or some other yield point (eg. undefined behaviour)

type CoProcExecutionState 

type CoProcExecutionState struct {
	Sync  CoProcSynchronisation
	Yield CoProcYield
}

CoProcExecutionState details the current condition of the coprocessor's execution

type CoProcSynchronisation 

type CoProcSynchronisation int

CoProcSynchronisation is used to describe the VCS synchronisation state of the coprocessor 

const (
	// the idle state means that the coprocessor is not interacting with the
	// VCS at that moment. the coprocessor might be running but it is waiting
	// to be instructed by the VCS program
	CoProcIdle CoProcSynchronisation = iota

	// a NOP feed describes the state where a cartridge mapper is waiting for
	// the coprocessor to finish processing. in the meantime, the cartridge is
	// feeding NOP instructions to the VCS
	CoProcNOPFeed

	// a StrongARM feed describes the state where the coprocessor has yielded
	// to the VCS in order for the next instruction to be read by the 6507
	CoProcStrongARMFeed

	// parallel execution describes the state where the coprocessor is running
	// without immediate concern with VCS synchronisation
	CoProcParallel
)

List of valid CoProcSynchronisation values.

A mapper will probably not employ all of these states depending on the synchronisation strategy. In reality the state will alternate between Idle-and-NOPFeed and StronARMFeed-and-Parallel.

Other synchronisation strategies may need the addition of additional states or a different mechanism altogether.

func (CoProcSynchronisation) String 

func (s CoProcSynchronisation) String() string

type CoProcYield 

type CoProcYield struct {
	Type  CoProcYieldType
	Error error
}

CoProcYield describes a coprocessor yield state

type CoProcYieldType 

type CoProcYieldType int

CoProcYieldType specifies the type of yield. This is a broad categorisation 

const (
	// the coprocessor has yielded because the program has ended. in this instance the
	// CoProcessor is not considered to be in a "yielded" state and can be modified
	//
	// Expected YieldReason for CDF and DPC+ type ROMs
	YieldProgramEnded CoProcYieldType = iota

	// the coprocessor has reached a synchronisation point in the program. it
	// must wait for the VCS before continuing
	//
	// Expected YieldReason for ACE and ELF type ROMs
	YieldSyncWithVCS

	// a user supplied breakpoint has been encountered
	YieldBreakpoint

	// the program has triggered undefined behaviour in the coprocessor
	YieldUndefinedBehaviour

	// the program has triggered an unimplemented feature in the coprocessor
	YieldUnimplementedFeature

	// the program has tried to access memory illegally. details will have been
	// communicated by the IllegalAccess() function of the CartCoProcDeveloper
	// interface
	YieldMemoryAccessError

	// something has gone wrong with the stack
	YieldStackError

	// execution error indicates that something has gone very wrong
	YieldExecutionError

	// the coprocessor has not yet yielded and is still running
	YieldRunning
)

List of CoProcYieldType values

func (CoProcYieldType) Bug 

func (t CoProcYieldType) Bug() bool

Bug returns true if the yield type indicates a likely bug

func (CoProcYieldType) Normal 

func (t CoProcYieldType) Normal() bool

Normal returns true if yield type is expected during normal operation of the coprocessor

func (CoProcYieldType) String 

func (t CoProcYieldType) String() string

type ExtendedRegisterGroup 

type ExtendedRegisterGroup struct {
	// name of the group
	Name string

	// the numeric range of the registers in this group
	Start int
	End   int

	// whether the register range is private to the implementation. a private
	// range means that is not meaningul in relation to DWARF
	Private bool

	// whether the registers in the group will return meaningful data from the
	// RegisterFormatted() function
	Formatted bool

	// the label to use for the register
	Label func(register int) string
}

ExtendedRegisterGroup specifies the numeric range for a coprocessor register group

type ExtendedRegisterSpec 

type ExtendedRegisterSpec []ExtendedRegisterGroup

ExtendedRegisterSpec is the specification returned by CartCoProc.RegisterSpec() function

func (ExtendedRegisterSpec) Group 

func (spec ExtendedRegisterSpec) Group(name string) (ExtendedRegisterGroup, bool)

Group returns the ExtendedRegisterGroup from the specifciation if it exists. For the purposes of this function, group names are not case-sensitive

type StubCartYieldHook 

type StubCartYieldHook struct{}

StubCartYieldHook is a stub implementation for the CartYieldHook interface.

func (StubCartYieldHook) CartYield 

func (_ StubCartYieldHook) CartYield(yld CoProcYieldType) YieldHookResponse

CartYield is a stub implementation for the CartYieldHook interface.

type YieldHookResponse 

type YieldHookResponse int

YieldHookResponse is returned by the CartYieldHook implementation to instruct the mapper in how to proceed 

const (
	YieldHookContinue YieldHookResponse = iota
	YieldHookEnd
)

List of valid YieldHookCommands

Source Files

View all Source files

Directories

Path Synopsis
Package developer offers additional functionality to the developer of ROMs that use a coprocessor.
 Package developer offers additional functionality to the developer of ROMs that use a coprocessor.
breakpoints
Package breakpoints records the breakpoints assigned to memory addresses.
 Package breakpoints records the breakpoints assigned to memory addresses.
callstack
Package callstack maintains the callstack of an executing program as accurately as possible.
 Package callstack maintains the callstack of an executing program as accurately as possible.
dwarf
dwarf/leb128
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.
faults
Package faults records memory faults generated by a coprocessor.
 Package faults records memory faults generated by a coprocessor.
mapfile
Package mapfile reads a mapfile produced by GCC and parses it.
 Package mapfile reads a mapfile produced by GCC and parses it.
profiling
Package profiling defines the types that are used to profile the performance of the coporocessor program.
 Package profiling defines the types that are used to profile the performance of the coporocessor program.
yield
Package yield records the current yielded state of a coprocessor.
 Package yield records the current yielded state of a coprocessor.
Package disassembly facilitates the disassembly of any coprocessor program in compatible ROM.
 Package disassembly facilitates the disassembly of any coprocessor program in compatible ROM.

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.