arch

type Architecture interface {
	// BankWindowSize returns the bank window size.
	BankWindowSize(cart *cartridge.Cartridge) int
	// Constants returns the constants translation map.
	Constants() (map[uint16]Constant, error)
	// GetAddressingParam returns the address of the param if it references an address.
	GetAddressingParam(param any) (uint16, bool)
	// HandleDisambiguousInstructions translates disambiguous instructions into data bytes as it
	// has multiple opcodes for the same addressing mode which can result in different
	// bytes being assembled and make the resulting ROM not matching the original.
	HandleDisambiguousInstructions(dis Disasm, address uint16, offsetInfo *Offset) bool
	// Initialize the architecture.
	Initialize(dis Disasm) error
	// IsAddressingIndexed returns if the opcode is using indexed addressing.
	IsAddressingIndexed(opcode Opcode) bool
	// LastCodeAddress returns the last possible address of code.
	// This is used in systems where the last address is reserved for
	// the interrupt vector table.
	LastCodeAddress() uint16
	// ProcessOffset processes an offset and returns if the offset was processed and an error if any.
	ProcessOffset(dis Disasm, address uint16, offsetInfo *Offset) (bool, error)
	// ProcessVariableUsage processes the variable usage of an offset.
	ProcessVariableUsage(offsetInfo *Offset, reference string) error
	// ReadOpParam reads the parameter of an opcode.
	ReadOpParam(dis Disasm, addressing int, address uint16) (any, []byte, error)
}

type BankReference struct {
	Mapped  MappedBank // bank reference
	Address uint16     // address in the bank
	ID      int        // bank ID
	Index   uint16     // index in the bank
}

type Constant struct {
	Address uint16

	Read  string
	Write string
}

type ConstantManager interface {
	// AddBank adds a new bank to the constants manager.
	AddBank()
	// Process processes all constants and updates all banks with the used ones. There is currently no tracking
	// for in which bank a constant is used, it will be added to all banks for now.
	Process()
	// ReplaceParameter replaces the parameter of an instruction by a constant name
	// if the address of the instruction is found in the constants map.
	ReplaceParameter(address uint16, opcode Opcode, paramAsString string) (string, bool)
	// SetBankConstants sets the used constants in the bank for outputting.
	SetBankConstants(bankID int, prgBank *program.PRGBank)
	// SetToProgram sets the used constants in the program for outputting.
	SetToProgram(app *program.Program)
}

type Disasm interface {
	// AddAddressToParse adds an address to the list to be processed if the address has not been processed yet.
	AddAddressToParse(address, context, from uint16, currentInstruction Instruction, isABranchDestination bool)
	// Cart returns the loaded cartridge.
	Cart() *cartridge.Cartridge
	// ChangeAddressRangeToCodeAsData sets a range of code address to code as
	// data types. It combines all data bytes that are not split by a label.
	ChangeAddressRangeToCodeAsData(address uint16, data []byte)
	// CodeBaseAddress returns the code base address.
	CodeBaseAddress() uint16
	// Constants returns the constants manager.
	Constants() ConstantManager
	// DeleteFunctionReturnToParse deletes a function return address from the list of addresses to parse.
	DeleteFunctionReturnToParse(address uint16)
	// JumpEngine returns the jump engine.
	JumpEngine() JumpEngine
	// Logger returns the logger.
	Logger() *log.Logger
	// Mapper returns the mapper.
	Mapper() Mapper
	// Options returns the disassembler options.
	Options() options.Disassembler
	// ProgramCounter returns the current program counter of the execution tracer.
	ProgramCounter() uint16
	// ReadMemory reads a byte from the memory at the given address.
	ReadMemory(address uint16) (byte, error)
	// ReadMemoryWord reads a word from the memory at the given address.
	ReadMemoryWord(address uint16) (uint16, error)
	// SetCodeBaseAddress sets the code base address.
	SetCodeBaseAddress(address uint16)
	// SetHandlers sets the program vector handlers.
	SetHandlers(handlers program.Handlers)
	// SetVectorsStartAddress sets the start address of the vectors.
	SetVectorsStartAddress(address uint16)
	// Variables returns the variable manager.
	Variables() VariableManager
}

type Instruction interface {
	// IsCall returns true if the instruction is a call.
	IsCall() bool
	// IsNil returns true if the instruction is nil.
	IsNil() bool
	// Name returns the instruction name.
	Name() string
	// Unofficial returns true if the instruction is not official.
	Unofficial() bool
}

type JumpEngine interface {
	// AddJumpEngine adds a jump engine function address to the list of jump engines.
	AddJumpEngine(address uint16)
	// GetContextDataReferences parse all instructions of the function context until the jump
	// and returns data references that could point to the function table.
	GetContextDataReferences(dis Disasm, offsets []*Offset, addresses []uint16) ([]uint16, error)
	// GetFunctionTableReference detects a jump engine function context and its function table.
	GetFunctionTableReference(context uint16, dataReferences []uint16)
	// HandleJumpEngineDestination processes a newly detected jump engine destination.
	HandleJumpEngineDestination(dis Disasm, caller, destination uint16) error
	// HandleJumpEngineCallers processes all callers of a newly detected jump engine function.
	HandleJumpEngineCallers(dis Disasm, context uint16) error
	// JumpContextInfo builds the list of instructions of the current function context.
	JumpContextInfo(dis Disasm, jumpAddress uint16, offsetInfo *Offset) ([]*Offset, []uint16)
	// ScanForNewJumpEngineEntry scans all jump engine calls for an unprocessed entry in the function address table that
	// follows the call. It returns whether a new address to parse was added.
	ScanForNewJumpEngineEntry(dis Disasm) (bool, error)
}

type MappedBank interface {
	ID() int
	OffsetInfo(address uint16) *Offset
}

type Mapper interface {
	GetMappedBank(address uint16) MappedBank
	GetMappedBankIndex(address uint16) uint16
	// OffsetInfo returns the offset information for the given address.
	OffsetInfo(address uint16) *Offset
}

type Offset struct {
	program.Offset

	Opcode Opcode // opcode this offset represents

	BranchFrom  []BankReference // list of all addresses that branch to this offset
	BranchingTo string          // label to jump to if instruction branches
	Context     uint16          // function or interrupt context that the offset is part of
}

type Opcode interface {
	// Addressing returns the addressing mode of the opcode.
	Addressing() int
	// Instruction returns the instruction of the opcode.
	Instruction() Instruction
	// ReadsMemory returns true if the opcode reads memory.
	ReadsMemory() bool
	// ReadWritesMemory returns true if the opcode reads and writes memory.
	ReadWritesMemory() bool
	// WritesMemory returns true if the opcode writes memory.
	WritesMemory() bool
}

type VariableManager interface {
	// AddBank adds a new bank to the variable manager.
	AddBank()
	// AddReference adds a variable reference if the opcode is accessing
	// the given address directly by reading or writing.
	AddReference(dis Disasm, addressReference, usageAddress uint16, opcode Opcode, forceVariableUsage bool)
	// Process processes all variables and updates the instructions that use them
	// with a generated alias name.
	Process(dis Disasm) error
	// SetBankVariables sets the used constants in the bank for outputting.
	SetBankVariables(bankID int, prgBank *program.PRGBank)
	// SetToProgram sets the used constants in the program for outputting.
	SetToProgram(app *program.Program)
}