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 repsective 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 Debugger
  • func NewDebugger(tv television.Television, scr gui.GUI, term terminal.Terminal) (*Debugger, error)
  • func (dbg *Debugger) GetLastResult() disassembly.Entry
  • func (dbg *Debugger) GetQuantum() QuantumMode
  • func (dbg *Debugger) GetReqFPS() float32
  • func (dbg *Debugger) HasBreak(e *disassembly.Entry) BreakGroup
  • func (dbg *Debugger) PushRawEvent(f func())
  • func (dbg *Debugger) SetFPS(fps float32)
  • func (dbg *Debugger) Start(initScript string, cartload cartridgeloader.Loader) error
  • func (dbg *Debugger) TogglePCBreak(e *disassembly.Entry)
• type Preferences
  • func (p Preferences) String() string
• type QuantumMode
  • func (mode QuantumMode) 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 Debugger

type Debugger struct {
	VCS    *hardware.VCS
	Disasm *disassembly.Disassembly

	// preferences
	Prefs *Preferences
	// 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(tv television.Television, scr gui.GUI, term terminal.Terminal) (*Debugger, error)

NewDebugger creates and initialises everything required for a new debugging session. Use the Start() method to actually begin the session.

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() QuantumMode

GetQuantum returns the current quantum value

func (*Debugger) GetReqFPS

func (dbg *Debugger) GetReqFPS() float32

GetReqFPS returens the requested number of frames per second. The limiter type has no GetActualFPS() function. Use the equivalent function from the television implementation.

*Use this in preference to SetFPS() from the television implementation*

func (*Debugger) HasBreak

func (dbg *Debugger) HasBreak(e *disassembly.Entry) 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) PushRawEvent

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

PushRawEvent onto the event queue. This can be used to get information out of the debygger into another goroutine. Useful for when there is no equivalent terminal command.

func (*Debugger) SetFPS

func (dbg *Debugger) SetFPS(fps float32)

SetFPS requests the number frames per second that the emulation should aim for. This overrides the frame rate of the specification. A negative FPS value restores the specifcications frame rate.

Note that this is only a request, the emulation may not be able to achieve that rate.

*Use this in preference to SetFPS() from the television implementation*

func (*Debugger) Start

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

Start the main debugger sequence.

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

type Preferences

type Preferences struct {
	RandomState *prefs.Bool
	RandomPins  *prefs.Bool
	// contains filtered or unexported fields
}

Preferences defines and collates all the preference values used by the debugger

func (Preferences) String

func (p Preferences) String() string

type QuantumMode

type QuantumMode int

QuantumMode specifies the step granularity of the emulator

const (
	QuantumCPU QuantumMode = iota
	QuantumVideo
)

List of valid QuantumModes

func (QuantumMode) String

func (mode QuantumMode) String() string