mapper

type BankContent struct {
	// bank number
	Number int

	// copy of the bank data
	Data []uint8

	// the segment origins that this data is allowed to be mapped to. most
	// cartridges will have one entry. values in the array will refer to
	// addresses in the cartridge address space. by convention the mappers will
	// refer to the primary mirror.
	//
	//	memorymap.OriginCart <= origins[n] <= memorymap.MemtopCart
	//
	// to index the Data field, transform the origin and any address derived
	// from it, with memorymap.CartridgeBits
	//
	//	idx := Origins[0] & memorymap.CartridgeBits
	//	v := Data[idx]
	//
	// address values are supplied by the mapper implementation and must be
	// cartridge addresses and should in the primary cartridge mirror range
	// (ie. 0x1000 to 0x1fff)j
	Origins []uint16
}

type BankInfo struct {
	// bank number
	Number int

	// name of bank. used for special purpose banks (eg. supercharger BIOS).
	// should be empty if bank has no name.
	Name string

	// is cartridge memory segmented and if so which segment is this bank
	// mapped to
	IsSegmented bool
	Segment     int

	// is cartridge bank writable
	IsRAM bool

	// if the address used to generate the Details is not a cartridge address.
	// this happens deliberately for example, during the Supercharger load
	// procedure, where execution happens (briefly) inside the main VCS RAM
	NonCart bool

	// the cartridge is currently feeding NOP bytes onto the data bus and
	// therefore the data from this bank should not be considered predictable.
	//
	// this flag has been added to support the ARM coprocessor found in
	// conjunction with CDF* and DPC+ mappers. future coprocessors may work
	// differently.
	ExecutingCoprocessor bool

	// if ExecutingCoprocessor is valid then we also record the address the
	// processor will resume from.
	CoprocessorResumeAddr uint16
}

type CartBusStuff interface {
	BusStuff() (uint8, bool)
}

type CartContainer interface {
	CartMapper
	ContainerID() string
}

type CartHotspotAction int

type CartHotspotInfo struct {
	Symbol string
	Action CartHotspotAction
}

type CartHotspotsBus interface {
	ReadHotspots() map[uint16]CartHotspotInfo
	WriteHotspots() map[uint16]CartHotspotInfo
}

type CartLabels map[uint16]string

type CartLabelsBus interface {
	Labels() CartLabels
}

type CartMapper interface {
	MappedBanks() string
	ID() string

	Snapshot() CartMapper
	Plumb(*environment.Environment)

	// reset volatile areas of the cartridge. for many cartridge mappers this
	// will do nothing but those with registers or ram should perform an
	// explicit reset (possibly with randomisation)
	Reset()

	// access the cartridge at the specified address. the cartridge is expected to
	// drive the data bus and so this can be thought of as a "read" operation
	//
	// the mask return value allows the mapper to identify which data pins
	// which are being driven by the cartridge. in most cases, the mask should
	// be the CartDrivenPins value
	//
	// the address parameter should be normalised. ie. no mirror information
	Access(addr uint16, peek bool) (data uint8, mask uint8, err error)

	// access the cartridge at the specified volatile address. if the location
	// at that address is not volatile, the data value can be ignored
	//
	// we can think of this as a write operation but it will be called during a
	// read operation too. this is because the cartidge cannot distinguish read
	// and write operations and any access of a volatile address will affect it
	//
	// the address parameter should be normalised. ie. no mirror information
	AccessVolatile(addr uint16, data uint8, poke bool) error

	NumBanks() int
	GetBank(addr uint16) BankInfo

	// AccessPassive is called so that the cartridge can respond to changes to the
	// address and data bus even when the data bus is not addressed to the cartridge.
	//
	// see the commentary for the AccessPassive() function in the Cartridge type
	// for an explanation for why this is needed
	AccessPassive(addr uint16, data uint8) error

	// some cartridge mappings have independent clocks that tick and change
	// internal cartridge state. the step() function is called every cpu cycle
	// at the rate specified.
	Step(clock float32)

	// return copies of all banks in the cartridge. the disassembly process
	// uses this to access cartridge data freely and without affecting the
	// state of the cartridge.
	CopyBanks() []BankContent
}

type CartPatchable interface {
	// patch is different to poke in that it alters the data as though it was
	// being read from disk. that is, the offset is measured from the start of
	// the file. the cartmapper must translate the offset and update the correct
	// data structure as appropriate.
	Patch(offset int, data uint8) error
}

type CartRAM struct {
	Label  string
	Origin uint16
	Data   []uint8
	Mapped bool
}

type CartRAMbus interface {
	GetRAM() []CartRAM

	// Update the value at the index of the specified RAM bank. Note that this
	// is not the address; it refers to the Data array as returned by GetRAM()
	PutRAM(bank int, idx int, data uint8)
}

type CartROMDump interface {
	ROMDump(filename string) error
}

type CartRegisters interface {
	String() string
}

type CartRegistersBus interface {
	// GetRegisters returns a copy of the cartridge's registers
	GetRegisters() CartRegisters

	// Update a register in the cartridge with new data.
	//
	// Depending on the complexity of the cartridge, the register argument may
	// need to be a structured string to uniquely identify a register (eg. a
	// JSON string, although that's probably going over the top). The details
	// of what is valid should be specified in the documentation of the mappers
	// that use the CartRegistersbus.
	//
	// The data string will be converted to whatever type is required for the
	// register. For simple types then this will be usual Go representation,
	// (eg. true of false for boolean types) but it may be a more complex
	// representation. Again, the details of what is valid should be specified
	// in the mapper documentation.
	PutRegister(register string, data string)
}

type CartRewindBoundary interface {
	RewindBoundary() bool
}

type CartStatic interface {
	// returns a list of memory areas in the cartridge's static memory
	Segments() []CartStaticSegment

	// returns a copy of the data in the named segment. the segment name should
	// be taken from the Name field of one of the CartStaticSegment instances
	// returned by the Segments() function
	Reference(segment string) ([]uint8, bool)

	// read 8, 16 or 32 bit values from the address. the address should be in
	// the range given in one of the CartStaticSegment returned by the
	// Segments() function.
	Read8bit(addr uint32) (uint8, bool)
	Read16bit(addr uint32) (uint16, bool)
	Read32bit(addr uint32) (uint32, bool)
}

type CartStaticBus interface {
	// GetStatic returns a copy of the cartridge's static areas
	GetStatic() CartStatic

	// Update the value at the index of the specified segment. the segment
	// argument should come from the Name field of the CartStaticSegment type
	// returned by CartStatic.Segments()
	//
	// The idx field should count from 0 and be no higher than the size of
	// memory in the segment (the differenc of Memtop and Origin returned in
	// the CartStaticSegment type).
	//
	// Returns false if segment is unknown or idx is out of range.
	//
	// PutStatic() will be working on the original data so PutStatic() should be
	// run in the same goroutine as the main emulation.
	PutStatic(segment string, idx int, data uint8) bool
}

type CartStaticSegment struct {
	Name   string
	Origin uint32
	Memtop uint32
}

type CartSuperChargerFastLoad interface {
	Fastload(mc *cpu.CPU, ram *vcs.RAM, tmr *timer.Timer) error
}

type CartTapeBus interface {
	// Move tape loading to the beginning of the tape
	Rewind()

	// Set tape counter to specified value
	SetTapeCounter(c int)

	// GetTapeState retrieves a copy of the current state of the tape. returns
	// false if state is not valid.
	GetTapeState() (bool, CartTapeState)
}

type CartTapeState struct {
	Counter    int
	MaxCounter int
	Time       float64
	MaxTime    float64
	Data       []float32
}

type OptionalSuperchip interface {
	// the force argument causes the superchip to be added whether it needs it or not
	AddSuperchip(force bool)
}

type PlumbFromDifferentEmulation interface {
	PlumbFromDifferentEmulation(*environment.Environment)
}