disassembly

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2020 License: GPL-3.0, GPL-3.0 Imports: 15 Imported by: 0

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 type provides a convenient way of iterating of the disassembly entries. It takes care of empty entries and entries not of the correct entry type.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bank 

type Bank int

Bank refers to the cartridge bank or one of a group of special conditions. 

const (
	BankUnknown Bank = -1
	BankRAM     Bank = -2
)

List of allowed Bank special conditions.

func (Bank) String 

func (b Bank) String() string

type Disassembly 

type Disassembly struct {

	// 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 (*Disassembly) BlessEntry 

func (dsm *Disassembly) BlessEntry(bank int, address uint16)

BlessEntry promotes an entry to the stated EntryLevel

func (*Disassembly) FormatResult 

func (dsm *Disassembly) FormatResult(bank int, 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 added in v0.2.1 

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.

func (*Disassembly) GetEntryByAddress 

func (dsm *Disassembly) GetEntryByAddress(bank int, address uint16) (*Entry, bool)

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) NewIteration 

func (dsm *Disassembly) NewIteration(minLevel EntryLevel, bank int) (*Iterate, int, error)

NewIteration initialises a new iteration of a dissasembly bank. The minLevel argument specifies the minumum entry level which should 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) NumBanks added in v0.2.1 

func (dsm *Disassembly) NumBanks() int

NumBanks returns the number of banks in the disassembly.

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 int

	// BankDecorated is a "decorated" instance of the Bank integer. Positive
	// values can be cast to int and treated just like Bank. However,
	// BankDecorated can also take other values that indicate special
	// conditions. The allowed values are defined above.
	BankDecorated Bank

	// 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
}

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

func (*Entry) String added in v0.2.1 

func (d *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 (
	EntryLevelDead EntryLevel = iota
	EntryLevelDecoded
	EntryLevelBlessed
)

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.

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 Iterate 

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

Iterate faciliates traversal of the disassembly

func (*Iterate) Next 

func (itr *Iterate) Next() *Entry

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

func (*Iterate) SkipNext 

func (itr *Iterate) SkipNext(n int) *Entry

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

func (*Iterate) Start 

func (itr *Iterate) Start() *Entry

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

type WriteAttr 

type WriteAttr struct {
	ByteCode bool
	Raw      bool
}

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

Source Files

View all Source files

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.