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(vcs *hardware.VCS) (*Disassembly, error)
  • func (dsm *Disassembly) Bless(bank mapper.BankInfo, startAddress uint16)
  • func (dsm *Disassembly) ExecutedEntry(bank mapper.BankInfo, result execution.Result, nextAddr uint16) (*Entry, error)
  • func (dsm *Disassembly) FormatResult(bank mapper.BankInfo, result execution.Result, level EntryLevel) (*Entry, error)
  • func (dsm *Disassembly) FromMemory(cart *cartridge.Cartridge, symbols *symbols.Symbols) error
  • func (dsm *Disassembly) GetEntryByAddress(address uint16) *Entry
  • func (dsm *Disassembly) Grep(output io.Writer, scope GrepScope, search string, caseSensitive bool) error
  • func (dsm *Disassembly) NewBankIteration(minLevel EntryLevel, bank int) (*IterateBank, error)
  • func (dsm *Disassembly) NewCartIteration() *IterateCart
  • 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) GetField(field Field) string
  • func (e *Entry) String() string
• type EntryLevel
• type Field
• type GrepScope
• type IterateBank
  • func (bitr *IterateBank) Next() (int, *Entry)
  • func (bitr *IterateBank) SkipNext(n int, skipLabels bool) (int, *Entry)
  • func (bitr *IterateBank) Start() (int, *Entry)
• type IterateCart
  • func (citr *IterateCart) Next() (int, bool)
  • func (citr *IterateCart) Start() (int, bool)
• type Label
  • func (l Label) String() string
• type Operand
  • func (l Operand) String() string
• 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
	Symbols *symbols.Symbols

	// any cartridge coprocessor that we find
	Coprocessor *coprocessor.Coprocessor
	// 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(vcs *hardware.VCS) (*Disassembly, error)

func (*Disassembly) Bless

func (dsm *Disassembly) Bless(bank mapper.BankInfo, startAddress uint16)

Bless disassembly sequence from the specified bank/address. Will do nothing if bank is not a cartridge ROM bank.

func (*Disassembly) ExecutedEntry

func (dsm *Disassembly) ExecutedEntry(bank mapper.BankInfo, result execution.Result, nextAddr uint16) (*Entry, error)

ExecutedEntry creates an Entry from a cpu result that has actually been executed. The newly created Entry replaces the previous equivalent entry in the disassembly.

If the execution.Result was from an instruction in RAM (cartridge RAM or VCS RAM) then the newly created entry is returned but not stored anywhere in the Disassembly.

func (*Disassembly) FormatResult

func (dsm *Disassembly) FormatResult(bank mapper.BankInfo, 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, symbols *symbols.Symbols) 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) GetEntryByAddress

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

GetEntryByAddress returns the disassembly entry at the specified bank/address. a returned value of nil indicates the entry is not in the cartridge; this will usually mean the address is in main VCS RAM.

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, error)

NewBankIteration initialises a new iteration of a dissasembly bank. The minLevel argument specifies the minimum 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.

func (*Disassembly) NewCartIteration

func (dsm *Disassembly) NewCartIteration() *IterateCart

NewCartIteration is the preferred method of initialisation for the IterateCart type.

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 mapper.BankInfo

	// copy of the CPU execution. must not be updated except through
	// updateExecutionEntry() function
	Result execution.Result

	// string representations of information in execution.Result. GetField()
	// will apply white-space padding and should be preferred in most
	// instances.
	Label    Label
	Bytecode string
	Address  string
	Operator string
	Operand  Operand

	// formatted cycles information from instructions.Defintion
	DefnCycles string
	Cycles     string

	// information about the most recent execution of the entry
	//
	// should be empty if EntryLevel != EntryLevelExecuted
	ExecutionNotes string
	// contains filtered or unexported fields
}

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

func (*Entry) GetField

func (e *Entry) GetField(field Field) string

GetField returns the formatted field from the speficied Entry.

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 (
	EntryLevelUnmappable 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 preceding 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.

type Field

type Field int

Field identifies which part of the disassmbly entry is of interest.

const (
	FldLabel Field = iota
	FldBytecode
	FldAddress
	FldOperator
	FldOperand
	FldDefnCycles
	FldActualCycles
	FldActualNotes
)

List of valid fields.

type GrepScope

type GrepScope int

GrepScope limits the scope of the search.

const (
	GrepAll GrepScope = iota
	GrepOperator
	GrepOperand
)

List of available scopes.

type IterateBank

type IterateBank struct {

	// total number of entries in iteration with the specified minimum level
	EntryCount int

	// the number of those entries with a label
	LabelCount int
	// 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, skipLabels bool) (int, *Entry)

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

The skipLabels argument indicates that an entry with a label should count as two entries. This is useful for the sdlimgui disassembly window's list clipper (and maybe nothing else).

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 {

	// number of banks in cart iteration
	BankCount int
	// 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 Label

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

Label implements the Stringer interface. The String() implementation returns any address label for the entry. Use GetField() function for a white-space padded label.

func (Label) String

func (l Label) String() string

type Operand

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

Operand implements the Stringer interface. The String() implementation returns the operand (with symbols if appropriate). Use GetField function for white-space padded operand string.

func (Operand) String

func (l Operand) String() string

type Preferences

type Preferences struct {

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

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