coprocessor

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)
}

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
}

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)
}

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

type CartCoProcDisasmSummary interface {
	String() string
}

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)
}

type CartCoProcDisassemblerStdout struct {
}

type CartCoProcOrigin interface {
	ExecutableOrigin() uint32
}

type CartCoProcProfileEntry struct {
	Addr   uint32
	Cycles float32
}

type CartCoProcProfiler struct {
	Entries []CartCoProcProfileEntry
}

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)
}

type CartYieldHook interface {
	CartYield(CoProcYieldType) YieldHookResponse
}

type CoProcExecutionState struct {
	Sync  CoProcSynchronisation
	Yield CoProcYield
}

type CoProcSynchronisation int

type CoProcYield struct {
	Type  CoProcYieldType
	Error error
}

type CoProcYieldType int

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
}

type ExtendedRegisterSpec []ExtendedRegisterGroup

type StubCartYieldHook struct{}

type YieldHookResponse int