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, PushFunction() should be used.
Index ¶
- type CommandLineOptions
- type CreateUserInterface
- type Debugger
- func (dbg *Debugger) CartYield(reason mapper.YieldReason) bool
- func (dbg *Debugger) CatchUpLoop(tgt coords.TelevisionCoords) error
- func (dbg *Debugger) Debugger() *Debugger
- func (dbg *Debugger) GotoCoords(coords coords.TelevisionCoords) bool
- func (dbg *Debugger) InsertCartridge(filename string)
- func (dbg *Debugger) LazyGetLiveDisasmEntry() disassembly.Entry
- func (dbg *Debugger) LazyGetQuantum() Quantum
- func (dbg *Debugger) LazyHasChanged() bool
- func (dbg *Debugger) LazyQueryBreakpoints() LazyBreakpointsQuery
- func (dbg *Debugger) Mode() govern.Mode
- func (dbg *Debugger) Plugged(port plugging.PortID, peripheral plugging.PeripheralID)
- func (dbg *Debugger) PushDeepPoke(addr uint16, value uint8, newValue uint8, valueMask uint8, done func()) bool
- func (dbg *Debugger) PushFunction(f func())
- func (dbg *Debugger) PushFunctionImmediate(f func())
- func (dbg *Debugger) PushSetMode(mode govern.Mode)
- func (dbg *Debugger) PushSetPause(paused bool)
- func (dbg *Debugger) PushTogglePCBreak(e *disassembly.Entry)
- func (dbg *Debugger) ReloadCartridge()
- 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) StartInDebugMode(filename string) error
- func (dbg *Debugger) StartInPlayMode(filename string) error
- func (dbg *Debugger) State() govern.State
- func (dbg *Debugger) TV() *television.Television
- func (dbg *Debugger) UserInput() chan userinput.Event
- func (dbg *Debugger) VCS() *hardware.VCS
- type LazyBreakpointsQuery
- type Preferences
- type Quantum
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CommandLineOptions ¶ added in v0.19.3
type CommandLineOptions struct { // common to debugger and play modes Log *bool Spec *string FpsCap *string Multiload *int Mapping *string Left *string Right *string Profile *string ELF *string // playmode only ComparisonROM *string ComparisonPrefs *string Record *bool PlaybackCheckROM *bool PatchFile *string Wav *bool NoEject *bool Macro *string // debugger only InitScript *string TermType *string }
CommandLineOptions holds all the values that can be specified on the command line when launching the application. Some arguments are used by both modes while some are mode specific.
The reason why we maintain pointers to the values is because we are using the modalflag package and by induction the flag package in the standard library, which is where this requirement originates.
func NewCommandLineOptions ¶ added in v0.19.3
func NewCommandLineOptions() CommandLineOptions
NewCommandLineOptions creates a minimum instance of CommandLineOptions such that it is safe to dereference the fields in all situations.
The values of these fields are shared by type and will be the default values for that type. ie. a bool is false, an int is zero, etc. Care should be taken therefore to replace the instance with the result from the modalflag (or flag) package.
type CreateUserInterface ¶ added in v0.15.0
CreateUserInterface is used to initialise the user interface used by the emulation. It returns an instance of both the GUI and Terminal interfaces in the repsective packages.
type Debugger ¶
type Debugger struct { // preferences for the emulation Prefs *Preferences // cartridge disassembly // // * allocated when entering debugger mode Disasm *disassembly.Disassembly CoProcDisasm coprocDisasm.Disassembly CoProcDev coprocDev.Developer // 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(opts CommandLineOptions, create CreateUserInterface) (*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) CartYield ¶ added in v0.20.0
func (dbg *Debugger) CartYield(reason mapper.YieldReason) bool
CartYield implements the mapper.CartYieldHook interface.
func (*Debugger) CatchUpLoop ¶ added in v0.7.1
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) GotoCoords ¶ added in v0.15.0
func (dbg *Debugger) GotoCoords(coords coords.TelevisionCoords) bool
GotoCoords rewinds the emulation to the specified coordinates.
func (*Debugger) InsertCartridge ¶ added in v0.15.0
InsertCartridge into running emulation. If filename argument is empty the currently inserted cartridge will be reinserted.
It should not be run directly from the emulation/debugger goroutine, use insertCartridge() for that
func (*Debugger) LazyGetLiveDisasmEntry ¶ added in v0.19.3
func (dbg *Debugger) LazyGetLiveDisasmEntry() disassembly.Entry
LazyGetLiveDisasmEntry returns the formatted disasembly entry of the last CPU execution and the bank information.
func (*Debugger) LazyGetQuantum ¶ added in v0.19.3
LazyGetQuantum returns the current quantum value.
func (*Debugger) LazyHasChanged ¶ added in v0.19.3
LazyHasChanged returns true if emulation state has changed since last call to the function.
func (*Debugger) LazyQueryBreakpoints ¶ added in v0.19.3
func (dbg *Debugger) LazyQueryBreakpoints() LazyBreakpointsQuery
LazyQueryBreakpoints returns an instance of LazyBreakpointsQuery.
func (*Debugger) Plugged ¶ added in v0.15.0
func (dbg *Debugger) Plugged(port plugging.PortID, peripheral plugging.PeripheralID)
Plugged implements the plugging.PlugMonitor interface.
func (*Debugger) PushDeepPoke ¶ added in v0.10.1
func (dbg *Debugger) PushDeepPoke(addr uint16, value uint8, newValue uint8, valueMask uint8, done func()) 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) PushFunction ¶ added in v0.19.3
func (dbg *Debugger) PushFunction(f func())
PushFunction onto the event queue. Used to ensure that the events are inserted into the emulation loop correctly.
func (*Debugger) PushFunctionImmediate ¶ added in v0.19.3
func (dbg *Debugger) PushFunctionImmediate(f func())
PushFunctionImmediate is the same as PushFunction but the event handler will return to the input loop for immediate action.
func (*Debugger) PushSetMode ¶ added in v0.19.3
PushSetMode sets the mode of the emulation.
func (*Debugger) PushSetPause ¶ added in v0.19.3
PushSetPause sets the pause state of the emulation.
func (*Debugger) PushTogglePCBreak ¶ added in v0.19.3
func (dbg *Debugger) PushTogglePCBreak(e *disassembly.Entry)
PushTogglePCBreak sets or unsets a PC break at the address rerpresented by the disassembly entry.
func (*Debugger) ReloadCartridge ¶ added in v0.17.0
func (dbg *Debugger) ReloadCartridge()
ReloadCartridge inserts the current cartridge and states the emulation over.
It should not be run directly from the emulation/debugger goroutine, use reloadCartridge() for that
func (*Debugger) RerunLastNFrames ¶ added in v0.15.0
RerunLastNFrames measured from the current frame.
func (*Debugger) RewindByAmount ¶ added in v0.15.0
RewindByAmount moves forwards or backwards by specified frames. Negative numbers indicate backwards
func (*Debugger) RewindToFrame ¶ added in v0.15.0
RewindToFrame measure from the current frame.
func (*Debugger) StartInDebugMode ¶ added in v0.16.0
StartInDebugMode starts the emulation with the debugger activated.
func (*Debugger) StartInPlayMode ¶ added in v0.16.0
StartInPlaymode starts the emulation ready for game-play.
func (*Debugger) TV ¶ added in v0.15.0
func (dbg *Debugger) TV() *television.Television
TV implements the emulation.Emulation interface.
type LazyBreakpointsQuery ¶ added in v0.19.3
LazyBreakpointsQuery allows others packages to query the currently set breakpoints.
type Preferences ¶ added in v0.2.1
type Preferences struct { // last ROM to be loaded into the emulation RecentROM prefs.String // contains filtered or unexported fields }
func (*Preferences) Load ¶ added in v0.15.0
func (p *Preferences) Load() error
Load disassembly preferences and apply to the current disassembly.
func (*Preferences) Save ¶ added in v0.15.0
func (p *Preferences) Save() error
Save current disassembly preferences to disk.
func (*Preferences) String ¶ added in v0.2.1
func (p *Preferences) String() string
Source Files
¶
- commandline_options.go
- commands.go
- commands_help.go
- commands_template.go
- coproc_shim.go
- debugger.go
- deeppoke.go
- doc.go
- eventhandler.go
- halt.go
- halt_breakpoints.go
- halt_targets.go
- halt_traps.go
- halt_watches.go
- lazy.go
- loop_catchup.go
- loop_debugger.go
- loop_playmode.go
- preferences.go
- print.go
- prompt.go
- push.go
- quantum.go
- rewind.go
- traces.go
- userinput.go
Directories
¶
Path | Synopsis |
---|---|
Package dbgmem sits between the debugger and the acutal VCS memory.
|
Package dbgmem sits between the debugger and the acutal VCS memory. |
Package govern defines the types that define the current condition of the emulation.
|
Package govern defines the types that define the current condition of the emulation. |
Package script allows the debugger to record and replay debugging scripts.
|
Package script allows the debugger to record and replay debugging scripts. |
Package terminal defines the operations required for command-line interaction with the debugger.
|
Package terminal defines the operations required for command-line interaction with the debugger. |
colorterm
Package colorterm implements the Terminal interface for the gopher2600 debugger.
|
Package colorterm implements the Terminal interface for the gopher2600 debugger. |
colorterm/easyterm
Package easyterm is a wrapper for "github.com/pkg/term/termios".
|
Package easyterm is a wrapper for "github.com/pkg/term/termios". |
colorterm/easyterm/ansi
Package ansi defines ANSI control codes for styles and colours.
|
Package ansi defines ANSI control codes for styles and colours. |
commandline
Package commandline facilitates parsing of command line input.
|
Package commandline facilitates parsing of command line input. |
plainterm
Package plainterm implements the Terminal interface for the gopher2600 debugger.
|
Package plainterm implements the Terminal interface for the gopher2600 debugger. |