debugger

Documentation

Overview

Package debugger implements a reaonably comprehensive debugging tool. Features include:

• cartridge disassembly
• memory peek and poke
• cpu and video cycle stepping
• basic scripting
• breakpoints
• traps
• watches

Some of these features come courtesy of other packages, described elsewhere, and some are inherent in the gopher2600's emulation strategy, but all are nicely exposed via the debugger package.

Initialisation of the debugger is done with the NewDebugger() function

dbg, _ := debugger.NewDebugger(television, gui, term)

The tv, gui and term arguments must be instances of types that satisfy the respective interfaces. This gives the debugger great flexibility and should allow easy porting to new platforms

Interaction with the debugger is primarily through a terminal. The Terminal interface is defined in the terminal package. The colorterm and plainterm sub-packages provide good reference implementations.

The GUI helps visualise the television and coordinates events (keyboard, mouse) which the debugger can then poll. A good reference implementation of a debugging GUI can be in found the gui.sdldebug package.

The television argument should be an instance of TV. For all practical purposes this will be instance createed with television.NewTelevision(), but other implementations are possible if not yet available.

Once initialised, the debugger can be started with the Start() function.

dbg.Start(initScript, cartloader)

The initscript is a script previously created either by the script.Scribe package or by hand. The cartloader argument must be an instance of cartloader.

Interaction with the debugger for both user and programs that use the debugger, is through the Terminal interface (see terminal package). Where this is not possible, functions have been provided. For interaction from other goroutines, the PushRawEvent() function should be used.

Index

• type BreakGroup
• type CreateUserInterface
• type Debugger
  • func NewDebugger(create CreateUserInterface, spec string, useSavekey bool, fpsCap bool) (*Debugger, error)
  • func (dbg *Debugger) CatchUpLoop(tgt coords.TelevisionCoords) error
  • func (dbg *Debugger) Debugger() emulation.Debugger
  • func (dbg *Debugger) GetLastResult() disassembly.Entry
  • func (dbg *Debugger) GetQuantum() Quantum
  • func (dbg *Debugger) GotoCoords(coords coords.TelevisionCoords) bool
  • func (dbg *Debugger) HasBreak(addr uint16, bank int) BreakGroup
  • func (dbg *Debugger) HasChanged() bool
  • func (dbg *Debugger) InsertCartridge(filename string) error
  • func (dbg *Debugger) IsDeepPoking() bool
  • func (dbg *Debugger) Mode() emulation.Mode
  • func (dbg *Debugger) Plugged(port plugging.PortID, peripheral plugging.PeripheralID)
  • func (dbg *Debugger) PushDeepPoke(addr uint16, value uint8, newValue uint8, valueMask uint8) bool
  • func (dbg *Debugger) PushRawEvent(f func())
  • func (dbg *Debugger) PushRawEventReturn(f func())
  • func (dbg *Debugger) RerunLastNFrames(frames int) bool
  • func (dbg *Debugger) RewindByAmount(amount int) bool
  • func (dbg *Debugger) RewindToFrame(fn int, last bool) bool
  • func (dbg *Debugger) SetFeature(request emulation.FeatureReq, args ...emulation.FeatureReqData) error
  • func (dbg *Debugger) Start(mode emulation.Mode, initScript string, cartload cartridgeloader.Loader) error
  • func (dbg *Debugger) State() emulation.State
  • func (dbg *Debugger) TV() emulation.TV
  • func (dbg *Debugger) TogglePCBreak(e *disassembly.Entry)
  • func (dbg *Debugger) UserInput() chan userinput.Event
  • func (dbg *Debugger) VCS() emulation.VCS
• type Preferences
  • func (p *Preferences) Load() error
  • func (p *Preferences) Save() error
  • func (p *Preferences) String() string
• type Quantum
  • func (mode Quantum) String() string

Types

type BreakGroup

type BreakGroup int

BreakGroup indicates the broad category of breakpoint an address has.

const (
	BrkNone BreakGroup = iota

	// a breakpoint.
	BrkPCAddress

	// a breakpoint on something other than the program counter / address.
	BrkOther
)

List of valid BreakGroup values.

type CreateUserInterface

type CreateUserInterface func(emulation.Emulation) (gui.GUI, terminal.Terminal, error)

CreateUserInterface is used to initialise the user interface used by the emulation.

type Debugger

type Debugger struct {

	// preferences for the emulation
	Prefs *Preferences

	// cartridge disassembly
	//
	// * allocated when entering debugger mode
	Disasm *disassembly.Disassembly

	// the Rewind system stores and restores machine state
	Rewind *rewind.Rewind

	// audio tracker stores audio state over time
	Tracker *tracker.Tracker
	// contains filtered or unexported fields
}

Debugger is the basic debugging frontend for the emulation. In order to be kind to code that accesses the debugger from a different goroutine (ie. a GUI), we try not to reinitialise anything once it has been initialised. For example, disassembly on a cartridge change (which can happen at any time) updates the Disasm field, it does not reinitialise it.

func NewDebugger

func NewDebugger(create CreateUserInterface, spec string, useSavekey bool, fpsCap bool) (*Debugger, error)

NewDebugger creates and initialises everything required for a new debugging session.

It should be followed up with a call to AddUserInterface() and call the Start() method to actually begin the emulation.

func (*Debugger) CatchUpLoop

func (dbg *Debugger) CatchUpLoop(tgt coords.TelevisionCoords) error

CatchUpLoop implements the rewind.Runner interface.

It is called from the rewind package and sets the functions that are required for catchupLoop().

func (*Debugger) Debugger

func (dbg *Debugger) Debugger() emulation.Debugger

Debugger implements the emulation.Emulation interface.

func (*Debugger) GetLastResult

func (dbg *Debugger) GetLastResult() disassembly.Entry

GetLastResult returns the formatted disasembly entry of the last CPU execution.

func (*Debugger) GetQuantum

func (dbg *Debugger) GetQuantum() Quantum

GetQuantum returns the current quantum value.

func (*Debugger) GotoCoords

func (dbg *Debugger) GotoCoords(coords coords.TelevisionCoords) bool

GotoCoords rewinds the emulation to the specified coordinates.

func (*Debugger) HasBreak

func (dbg *Debugger) HasBreak(addr uint16, bank int) BreakGroup

HasBreak returns true if there is a breakpoint at the address. the second return value indicates if there is a breakpoint at the address AND bank.

func (*Debugger) HasChanged

func (dbg *Debugger) HasChanged() bool

HasChanged returns true if emulation state has changed since last call to the function.

func (*Debugger) InsertCartridge

func (dbg *Debugger) InsertCartridge(filename string) error

InsertCartridge into running emulation.

func (*Debugger) IsDeepPoking

func (dbg *Debugger) IsDeepPoking() bool

IsDeepPoking returns true if a deep poke search is in progress.

func (*Debugger) Mode

func (dbg *Debugger) Mode() emulation.Mode

Mode implements the emulation.Emulation interface.

func (*Debugger) Plugged

func (dbg *Debugger) Plugged(port plugging.PortID, peripheral plugging.PeripheralID)

Plugged implements the plugging.PlugMonitor interface.

func (*Debugger) PushDeepPoke

func (dbg *Debugger) PushDeepPoke(addr uint16, value uint8, newValue uint8, valueMask uint8) bool

PushDeepPoke schedules a deep poke search for the specificed value in the address, replacing it with newValue if found. The valueMask will be applied to the value for matching and for setting the newValue - unset bits in the mask will preserve the corresponding bits in the found value.

func (*Debugger) PushRawEvent

func (dbg *Debugger) PushRawEvent(f func())

PushRawEvent onto the event queue.

Used to ensure that the events are inserted into the emulation loop correctly.

func (*Debugger) PushRawEventReturn

func (dbg *Debugger) PushRawEventReturn(f func())

PushRawEventReturn is the same as PushRawEvent but handlers will return to the input loop for immediate action.

func (*Debugger) RerunLastNFrames

func (dbg *Debugger) RerunLastNFrames(frames int) bool

RerunLastNFrames measured from the current frame.

func (*Debugger) RewindByAmount

func (dbg *Debugger) RewindByAmount(amount int) bool

RewindByAmount moves forwards or backwards by specified frames. Negative numbers indicate backwards

func (*Debugger) RewindToFrame

func (dbg *Debugger) RewindToFrame(fn int, last bool) bool

RewindToFrame measure from the current frame.

func (*Debugger) SetFeature

func (dbg *Debugger) SetFeature(request emulation.FeatureReq, args ...emulation.FeatureReqData) error

ReqFeature implements the emulation.Emulation interface.

func (*Debugger) Start

func (dbg *Debugger) Start(mode emulation.Mode, initScript string, cartload cartridgeloader.Loader) error

Starts the main emulation sequence.

func (*Debugger) State

func (dbg *Debugger) State() emulation.State

State implements the emulation.Emulation interface.

func (*Debugger) TV

func (dbg *Debugger) TV() emulation.TV

TV implements the emulation.Emulation interface.

func (*Debugger) TogglePCBreak

func (dbg *Debugger) TogglePCBreak(e *disassembly.Entry)

TogglePCBreak sets or unsets a PC break at the address rerpresented by th disassembly entry.

func (*Debugger) UserInput

func (dbg *Debugger) UserInput() chan userinput.Event

UserInput implements the emulation.Emulation interface.

func (*Debugger) VCS

func (dbg *Debugger) VCS() emulation.VCS

VCS implements the emulation.Emulation interface.

type Preferences

type Preferences struct {

	// last ROM to be loaded into the emulation
	RecentROM prefs.String
	// contains filtered or unexported fields
}

func (*Preferences) Load

func (p *Preferences) Load() error

Load disassembly preferences and apply to the current disassembly.

func (*Preferences) Save

func (p *Preferences) Save() error

Save current disassembly preferences to disk.

func (*Preferences) String

func (p *Preferences) String() string

type Quantum

type Quantum int

Quantum specifies the step granularity of the emulator.

const (
	QuantumInstruction Quantum = iota
	QuantumClock
)

List of valid QuantumModes.

func (Quantum) String

func (mode Quantum) String() string