symbols

Documentation

Overview

Package symbols helps keep track of address symbols for the currently loaded cartridge. It will load symbols from a DASM symbol file if one can be found. It also handles the allocation of standard (or canonical) symbol names.

In the context of the Gopher2600 project, it works best if the Symbol type is declared staticially and the ReadSymbolsFile() function called to populate the symbol tables. See the disassembly package for more details. Even if there is no symbols file, the tables will be populated with canonical names.

Also works best in conjunction with the parent disassembly package where the disassembly process will remove any labels from "unblessed" cartridge addresses.

All addresses supplied to functions in the symbols package will be mapped (ie. normalised) and symbols will be trimmed of excess space.

Index

• type Entry
• type SearchResults
• type SearchTable
• type SymbolSource
• type Symbols
  • func (sym *Symbols) AddLabel(source SymbolSource, bank int, addr uint16, symbol string) bool
  • func (sym *Symbols) AddLabelAuto(bank int, addr uint16) bool
  • func (sym *Symbols) AddSymbol(source SymbolSource, addr uint16, symbol string, read bool) bool
  • func (sym *Symbols) GetLabel(bank int, addr uint16) (Entry, bool)
  • func (sym *Symbols) GetSymbol(addr uint16, read bool) (Entry, bool)
  • func (sym *Symbols) LabelWidth() int
  • func (sym *Symbols) ListLabels(output io.Writer)
  • func (sym *Symbols) ListReadSymbols(output io.Writer)
  • func (sym *Symbols) ListSymbols(output io.Writer)
  • func (sym *Symbols) ListWriteSymbols(output io.Writer)
  • func (sym *Symbols) ReadSymbolsFile(cart *cartridge.Cartridge) error
  • func (sym *Symbols) RemoveLabel(bank int, addr uint16) bool
  • func (sym *Symbols) RemoveSymbol(addr uint16, read bool) bool
  • func (sym *Symbols) SearchByAddress(addr uint16, table SearchTable) *SearchResults
  • func (sym *Symbols) SearchBySymbol(symbol string, table SearchTable) *SearchResults
  • func (sym *Symbols) SymbolWidth() int
  • func (sym *Symbols) UpdateLabel(source SymbolSource, bank int, addr uint16, oldLabel string, newLabel string) bool
  • func (sym *Symbols) UpdateSymbol(source SymbolSource, addr uint16, oldLabel string, newLabel string, read bool) bool

Types

type Entry

type Entry struct {
	Symbol string
	Source SymbolSource
}

Entry records a symbol and the source of its definition.

type SearchResults

type SearchResults struct {
	// the table the result was found in
	Table SearchTable

	// the symbol as it exists in the table
	Entry Entry

	// the normalised address the symbol refers to
	Address uint16
}

SearchResults contains the normalised symbol/address info found in the requested SearchTable.

type SearchTable

type SearchTable string

SearchTable is used to select and identify a symbol table when searching.

const (
	SearchLabel SearchTable = "label"
	SearchRead  SearchTable = "read"
	SearchWrite SearchTable = "write"
)

List of valid symbol table identifiers.

type SymbolSource

type SymbolSource string

SymbolSource identifies the source of the symbol.

const (
	SourceDASM      SymbolSource = "DASM"
	SourceAuto      SymbolSource = "Auto"
	SourceSystem    SymbolSource = "System"
	SourceCartridge SymbolSource = "Cartridge"
	SourceCustom    SymbolSource = "Custom"
)

List of valid SymbolSource values.

type Symbols

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

Symbols contains the all currently defined symbols.

func (*Symbols) AddLabel

func (sym *Symbols) AddLabel(source SymbolSource, bank int, addr uint16, symbol string) bool

Add symbol to label table. Symbol will be modified so that it is unique in the label table.

func (*Symbols) AddLabelAuto

func (sym *Symbols) AddLabelAuto(bank int, addr uint16) bool

Add symbol to label table using a symbols created from the address information.

func (*Symbols) AddSymbol

func (sym *Symbols) AddSymbol(source SymbolSource, addr uint16, symbol string, read bool) bool

AddSymbol to read/write table. Symbol will be modified so that it is unique in the selected table.

The read argument selects the table: true -> read table, false -> write table.

func (*Symbols) GetLabel

func (sym *Symbols) GetLabel(bank int, addr uint16) (Entry, bool)

Get symbol from label table.

The problem with this function is that it can't handle getting labels if a JMP for example, triggers a bankswtich at the same time. We can see this in E7 type cartridges. For example the second instruction of HeMan JMPs from bank 7 to bank 5. Short of having a copy of the label in every bank, or more entwined knowledge of how cartridge mappers work, there's not a lot we can do about this.

func (*Symbols) GetSymbol

func (sym *Symbols) GetSymbol(addr uint16, read bool) (Entry, bool)

Getsymbol from read/write table.

The read argument selects the table: true -> read table, false -> write table.

func (*Symbols) LabelWidth

func (sym *Symbols) LabelWidth() int

LabelWidth returns the maximum number of characters required by a label in the label table.

func (*Symbols) ListLabels

func (sym *Symbols) ListLabels(output io.Writer)

ListLabels outputs every label used in the current ROM.

func (*Symbols) ListReadSymbols

func (sym *Symbols) ListReadSymbols(output io.Writer)

ListReadSymbols outputs every read symbol used in the current ROM.

func (*Symbols) ListSymbols

func (sym *Symbols) ListSymbols(output io.Writer)

ListSymbols outputs every symbol used in the current ROM.

func (*Symbols) ListWriteSymbols

func (sym *Symbols) ListWriteSymbols(output io.Writer)

ListWriteSymbols outputs every write symbol used in the current ROM.

func (*Symbols) ReadSymbolsFile

func (sym *Symbols) ReadSymbolsFile(cart *cartridge.Cartridge) error

ReadSymbolsFile initialises a symbols table from the symbols file for the specified cartridge. Even in the event of an error the Symbols table will still be usable and will contain the standard 2600 symbols.

Currently, only symbols files generated by DASM are supported.

func (*Symbols) RemoveLabel

func (sym *Symbols) RemoveLabel(bank int, addr uint16) bool

Remove label from label table. Symbol will be modified so that it is unique in the label table.

func (*Symbols) RemoveSymbol

func (sym *Symbols) RemoveSymbol(addr uint16, read bool) bool

RemoveSymbol from read/write table.

The read argument selects the table: true -> read table, false -> write table.

func (*Symbols) SearchByAddress

func (sym *Symbols) SearchByAddress(addr uint16, table SearchTable) *SearchResults

SearchByAddress returns the symbol for specified address. Address will be normalised before search.

func (*Symbols) SearchBySymbol

func (sym *Symbols) SearchBySymbol(symbol string, table SearchTable) *SearchResults

SearchBySymbol return the address of the supplied search string. Matching is case-insensitive.

func (*Symbols) SymbolWidth

func (sym *Symbols) SymbolWidth() int

SymbolWidth returns the maximum number of characters required by a symbol in the read/write table.

func (*Symbols) UpdateLabel

func (sym *Symbols) UpdateLabel(source SymbolSource, bank int, addr uint16, oldLabel string, newLabel string) bool

Update symbol in label table. Returns success.

func (*Symbols) UpdateSymbol

func (sym *Symbols) UpdateSymbol(source SymbolSource, addr uint16, oldLabel string, newLabel string, read bool) bool

UpdateSymbol in read/write table. Symbol will be modified so that it is unique in the selected table

The read argument selects the table: true -> read table, false -> write table.