debugger

package
v0.35.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 14, 2024 License: GPL-3.0 Imports: 70 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CheckBreakpoints added in v0.25.0 

type CheckBreakpoints interface {
	HasPCBreak(addr uint16, bank int) (bool, int)
}

CheckBreakpoints is a minimal interface to Breakpoints

type CommandLineOptions added in v0.19.3 

type CommandLineOptions struct {
	// common to debugger and play modes
	Log       bool
	Spec      string
	FpsCap    bool
	Multiload int
	Mapping   string
	Bank      string
	Left      string
	Right     string
	Swap      bool
	Profile   string
	ELF       string

	// playmode only
	ComparisonROM        string
	ComparisonPrefs      string
	Record               bool
	RecordFilename       string
	PlaybackCheckROM     bool
	PlaybackIgnoreDigest 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.

type CreateUserInterface added in v0.15.0 

type CreateUserInterface func(*Debugger) (gui.GUI, terminal.Terminal, error)

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

	// stella.Properties file support
	Properties properties.Properties

	// cartridge disassembly
	//
	// * allocated when entering debugger mode
	Disasm       *disassembly.Disassembly
	CoProcDisasm coproc_disasm.Disassembly
	CoProcDev    coproc_dev.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(yield coprocessor.CoProcYield) coprocessor.YieldHookResponse

CartYield implements the coprocessor.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) ClearHaltReason added in v0.33.0 

func (dbg *Debugger) ClearHaltReason()

ClearHaltReason clears the haltReason field in the haltCoordination type

func (*Debugger) Debugger added in v0.14.0 

func (dbg *Debugger) Debugger() *Debugger

Debugger implements the emulation.Emulation interface.

func (*Debugger) GetBreakpoints added in v0.25.0 

func (dbg *Debugger) GetBreakpoints() CheckBreakpoints

GetBreakpoints returns an instance of CheckBreakpoints. This is good for allowing other goroutines access to a read-only copy of the list of breakpoints.

func (*Debugger) GetHaltReason added in v0.33.0 

func (dbg *Debugger) GetHaltReason() string

GetHaltReason returns the haltReason field from the haltCoordination type

func (*Debugger) GetLiveDisasmEntry added in v0.16.0 

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

GetLiveDisasmEntry returns the formatted disasembly entry of the last CPU execution and the bank informations.String())

func (*Debugger) GotoCoords added in v0.15.0 

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

GotoCoords rewinds the emulation to the specified coordinates.

This function should be run only from debugger mode.

func (*Debugger) InsertCartridge added in v0.15.0 

func (dbg *Debugger) InsertCartridge(filename string)

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) Mode added in v0.15.0 

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

Mode implements the emulation.Emulation interface.

func (*Debugger) Notify added in v0.30.0 

func (dbg *Debugger) Notify(notice notifications.Notice) error

Notify implements the notifications.Notify interface

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) PushMemoryProfile added in v0.32.0 

func (dbg *Debugger) PushMemoryProfile()

PushMemoryProfile forces a garbage collection event and takes a runtime memory profile and saves it to the working directory

func (*Debugger) PushSetMode added in v0.19.3 

func (dbg *Debugger) PushSetMode(mode govern.Mode)

PushSetMode sets the mode of the emulation.

func (*Debugger) PushSetPause added in v0.19.3 

func (dbg *Debugger) PushSetPause(paused bool)

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) Quantum added in v0.25.0 

func (dbg *Debugger) Quantum() govern.Quantum

Mode implements the emulation.Emulation interface.

func (*Debugger) ReloadCartridge added in v0.17.0 

func (dbg *Debugger) ReloadCartridge()

ReloadCartridge inserts the current cartridge and states the emulation over.

func (*Debugger) RerunLastNFrames added in v0.15.0 

func (dbg *Debugger) RerunLastNFrames(frames int, onSplice rewind.SpliceHook) bool

RerunLastNFrames measured from the current frame.

This function should be run only from debugger mode.

func (*Debugger) RewindByAmount added in v0.15.0 

func (dbg *Debugger) RewindByAmount(amount int)

RewindByAmount moves forwards or backwards by specified frames. Positive numbers to "rewind" forwards and negative numbers to rewind backwards.

func (*Debugger) RewindToFrame added in v0.15.0 

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

RewindToFrame measure from the current frame.

This function should be run only from debugger mode.

func (*Debugger) StartInDebugMode added in v0.16.0 

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

StartInDebugMode starts the emulation with the debugger activated.

func (*Debugger) StartInPlayMode added in v0.16.0 

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

StartInPlaymode starts the emulation ready for game-play.

func (*Debugger) State added in v0.14.0 

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

State implements the emulation.Emulation interface.

func (*Debugger) SubState added in v0.30.0 

func (dbg *Debugger) SubState() govern.SubState

SubState implements the emulation.Emulation interface.

func (*Debugger) TV added in v0.15.0 

func (dbg *Debugger) TV() *television.Television

TV implements the emulation.Emulation interface.

func (*Debugger) UserInput added in v0.14.0 

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

UserInput implements the emulation.Emulation interface.

func (*Debugger) VCS added in v0.2.1 

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

VCS implements the emulation.Emulation interface.

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

View all Source files

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.

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.