disassembly

Documentation

Overview

Package disassembly coordinates the disassembly of Atari2600 (6507) cartridges.

For quick disassemblies the FromCartridge() function can be used. Debuggers will probably find it more useful however, to disassemble from the memory of an already instantiated VCS.

disasm, _ := disassembly.FromMemory(cartMem, symbols.NewTable())

The FromMemory() function takes an instance of a symbols.Table or nil. In the example above, the result of NewTable() has been used, which is fine but limits the potential of the disassembly package. For best results, the symbols.ReadSymbolsFile() function should be used (see symbols package for details). Note that the FromCartridge() function handles symbols files for you.

The Write() group of functions "print" disassambly entries of type EntryTypeDecode only. Useful for printing static disassemblies of a cartridge but probably not much else.

The iteration types provides a convenient way of iterating of the disassembly entries. It takes care of empty entries and entries not of the correct entry type.

The Grep() function provides a quick way of searching the disassembly with a scope directive. More complex search schemes can be written with the iteration types.

Index

• type Disassembly
  • func FromCartridge(cartload cartridgeloader.Loader) (*Disassembly, error)
  • func NewDisassembly() (*Disassembly, error)
  • func (dsm *Disassembly) FormatResult(bank banks.Details, result execution.Result, level EntryLevel) (*Entry, error)
  • func (dsm *Disassembly) FromMemory(cart *cartridge.Cartridge, symtable *symbols.Table) error
  • func (dsm *Disassembly) FromMemoryAgain(startAddress ...uint16) error
  • func (dsm *Disassembly) GetEntryByAddress(address uint16) *Entry
  • func (dsm *Disassembly) GetField(field Field, e *Entry) string
  • func (dsm *Disassembly) Grep(output io.Writer, scope GrepScope, search string, caseSensitive bool) error
  • func (dsm *Disassembly) NewBankIteration(minLevel EntryLevel, bank int) (*IterateBank, int, error)
  • func (dsm *Disassembly) NewCartIteration() (*IterateCart, int)
  • func (dsm *Disassembly) UpdateEntry(bank banks.Details, result execution.Result, nextAddr uint16) (*Entry, error)
  • func (dsm *Disassembly) Write(output io.Writer, attr WriteAttr) error
  • func (dsm *Disassembly) WriteBank(output io.Writer, attr WriteAttr, bank int) error
  • func (dsm *Disassembly) WriteEntry(output io.Writer, attr WriteAttr, e *Entry)
• type Entry
  • func (e *Entry) String() string
• type EntryLevel
  • func (t EntryLevel) String() string
• type Field
• type GrepScope
• type IterateBank
  • func (bitr *IterateBank) Next() (int, *Entry)
  • func (bitr *IterateBank) SkipNext(n int) (int, *Entry)
  • func (bitr *IterateBank) Start() (int, *Entry)
• type IterateCart
  • func (citr *IterateCart) Next() (int, bool)
  • func (citr *IterateCart) Start() (int, bool)
• type Preferences
  • func (p *Preferences) Load() error
  • func (p *Preferences) Save() error
  • func (p Preferences) String() string
• type WriteAttr

Types

type Disassembly

type Disassembly struct {
	Prefs *Preferences

	// symbols used to format disassembly output
	Symtable *symbols.Table
	// contains filtered or unexported fields
}

Disassembly represents the annotated disassembly of a 6507 binary

func FromCartridge

func FromCartridge(cartload cartridgeloader.Loader) (*Disassembly, error)

FromCartridge initialises a new partial emulation and returns a disassembly from the supplied cartridge filename. Useful for one-shot disassemblies, like the gopher2600 "disasm" mode.

func NewDisassembly

func NewDisassembly() (*Disassembly, error)

func (*Disassembly) FormatResult

func (dsm *Disassembly) FormatResult(bank banks.Details, result execution.Result, level EntryLevel) (*Entry, error)

FormatResult It is the preferred method of initialising for the Entry type. It creates a disassembly.Entry based on the bank and result information.

func (*Disassembly) FromMemory

func (dsm *Disassembly) FromMemory(cart *cartridge.Cartridge, symtable *symbols.Table) error

FromMemory disassembles an existing instance of cartridge memory using a cpu with no flow control. Unlike the FromCartridge() function this function requires an existing instance of Disassembly

cartridge will finish in its initialised state

func (*Disassembly) FromMemoryAgain

func (dsm *Disassembly) FromMemoryAgain(startAddress ...uint16) error

FromMemoryAgain repeats the disassembly using the existing structures

func (*Disassembly) GetEntryByAddress

func (dsm *Disassembly) GetEntryByAddress(address uint16) *Entry

GetEntryByAddress returns the disassembly entry at the specified bank/address.

func (*Disassembly) GetField

func (dsm *Disassembly) GetField(field Field, e *Entry) string

GetField returns the formatted field from the speficied Entry

func (*Disassembly) Grep

func (dsm *Disassembly) Grep(output io.Writer, scope GrepScope, search string, caseSensitive bool) error

Grep searches the disassembly for the specified search string.

func (*Disassembly) NewBankIteration

func (dsm *Disassembly) NewBankIteration(minLevel EntryLevel, bank int) (*IterateBank, int, error)

NewBankIteration initialises a new iteration of a dissasembly bank. The minLevel argument specifies the minumum entry level which should be returned in the iteration. So, using the following as a guide:

dead < decoded < blessed

Specifying a minLevel of EntryLevelDecode will iterate *only* entries of EntryLevelDecode. A minLevel of EntryLevelNaive on the other hand, will iterate through entries of EntryLevelNaive *and* EntryLevelDecode. A minLevel of EntryLevelDead will iterate through *all* Entries.

The function returns an instance of Iterate, a count of the number of entries the correspond to the minLevel (see above), and any error.

func (*Disassembly) NewCartIteration

func (dsm *Disassembly) NewCartIteration() (*IterateCart, int)

NewCartIteration is the preferred method of initialisation for the IterateCart type

func (*Disassembly) UpdateEntry

func (dsm *Disassembly) UpdateEntry(bank banks.Details, result execution.Result, nextAddr uint16) (*Entry, error)

UpdateEntry to more closely resemble the most recent execution.Result.

If the result is transient (ie. executed from RAM) then nothing is updated but a formatted result is returned.

func (*Disassembly) Write

func (dsm *Disassembly) Write(output io.Writer, attr WriteAttr) error

Write the entire disassembly to io.Writer

func (*Disassembly) WriteBank

func (dsm *Disassembly) WriteBank(output io.Writer, attr WriteAttr, bank int) error

WriteBank writes the disassembly of the selected bank to io.Writer

func (*Disassembly) WriteEntry

func (dsm *Disassembly) WriteEntry(output io.Writer, attr WriteAttr, e *Entry)

WriteEntry writes a single Instruction to io.Writer

type Entry

type Entry struct {
	// the level of reliability of the information in the Entry
	Level EntryLevel

	// execution.Result does not specify which bank the instruction is from
	// because that information isn't available to the CPU. we note it here if
	// possible.
	Bank banks.Details

	// copy of the CPU execution
	Result execution.Result

	// formatted strings representations of information in execution.Result
	Location string
	Bytecode string
	Address  string
	Mnemonic string
	Operand  string

	// formatted cycles and notes information from instructions.Defintion
	DefnCycles string
	DefnNotes  string

	// actual cycles and notes are the cycles and notes actually seen in
	// the computation
	ActualCycles string
	ActualNotes  string

	// does the entry represent an instruction that might have different
	// "actual" strings depending on the specifics of execution. practically,
	// this means branch and page-sensitive instructions
	UpdateActualOnExecute bool
}

Entry is a disassambled instruction. The constituent parts of the disassembly. It is a represenation of execution.Instruction

func (*Entry) String

func (e *Entry) String() string

String returns a very basic representation of an Entry. Provided for convenience. Probably not of any use except for the simplest of tools.

type EntryLevel

type EntryLevel int

EntryLevel describes the level of the Entry

const (
	EntryLevelUnused EntryLevel = iota
	EntryLevelDecoded
	EntryLevelBlessed
	EntryLevelExecuted
)

List of valid EntryL in increasing reliability.

Decoded entries have been decoded as though every byte point is a valid instruction. Blessed entries meanwhile take into consideration the preceeding instruction and the number of bytes it would have consumed.

Decoded entries are useful in the event of the CPU landing on an address that didn't look like an instruction at disassembly time.

Blessed instructions are deemed to be more accurate because they have been reached according to the flow of the instructions from the start address.

For normal debugging operations there is no need to use EntryLevelUnused outside of the disassembly package. It used for the unusual case where a bank is not able to be referenced from the Entry address. See M-Network for an example of this, where Bank 7 cannot be mapped to the lower segment.

func (EntryLevel) String

func (t EntryLevel) String() string

type Field

type Field int

Field identifies which part of the disassmbly entry is of interest

const (
	FldLocation Field = iota
	FldBytecode
	FldAddress
	FldMnemonic
	FldOperand
	FldDefnCycles
	FldDefnNotes
	FldActualCycles
	FldActualNotes
)

List of valid fields

type GrepScope

type GrepScope int

GrepScope limits the scope of the search

const (
	GrepMnemonic GrepScope = iota
	GrepOperand
	GrepAll
)

List of available scopes

type IterateBank

type IterateBank struct {
	// contains filtered or unexported fields
}

IterateBank faciliates traversal a specific bank.

Instances of Entry returned by Start(), Next() and SkipNext() are copies of the disassembly entry, so the Iterate mechanism is suitable for use in a goroutine different to that which is handling (eg. updating) the disassembly itslef.

func (*IterateBank) Next

func (bitr *IterateBank) Next() (int, *Entry)

Next entry in the disassembly of the previously specified type. Returns nil if end of disassembly has been reached.

func (*IterateBank) SkipNext

func (bitr *IterateBank) SkipNext(n int) (int, *Entry)

SkipNext n entries and return that Entry. An n value of < 0 returns the most recent value in the iteration

func (*IterateBank) Start

func (bitr *IterateBank) Start() (int, *Entry)

Start new iteration from the first instance of the EntryLevel specified in NewBankIteration.

type IterateCart

type IterateCart struct {
	// contains filtered or unexported fields
}

IterateCart faciliates traversal over all the banks in a cartridge.

func (*IterateCart) Next

func (citr *IterateCart) Next() (int, bool)

The next bank in the cartidge. Returns (-1, false) if there are no more banks.

func (*IterateCart) Start

func (citr *IterateCart) Start() (int, bool)

Start new iteration from the first bank

type Preferences

type Preferences struct {

	// whether to apply the high mirror bits to the displayed address
	FxxxMirror prefs.Bool
	// 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 WriteAttr

type WriteAttr struct {
	ByteCode bool
	Raw      bool
}

WriteAttr controls what is printed by the Write*() functions