bus

type CPUBus ¶

type CPUBus interface {
	Read(address uint16) (uint8, error)
	Write(address uint16, data uint8) error

	// implementations of ReadZeroPage may just pass the address onto the
	// Read() function and return, depending on what the implementation is
	// supposed to do. for the real vcs emulation however, a zero page read
	// has consequences
	ReadZeroPage(address uint8) (uint8, error)
}

CPUBus defines the operations for the memory system when accessed from the CPU All memory areas implement this interface because they are all accessible from the CPU (compare to ChipBus). The VCSMemory type also implements this interface and maps the read/write address to the correct memory area -- meaning that CPU access need not care which part of memory it is writing to

type CartDebugBus ¶ added in v0.2.1

type CartDebugBus 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 CartDebugBus.
	//
	// 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)

	// GetStatic returns a copy of the cartridge's static areas
	GetStatic() CartStatic
	PutStatic(addr uint16, data uint8) error
}

CartDebugBus defines the operations required for a debugger to access the static and special function areas of a cartrudge.

The mapper is allowed to panic if it is not interfaced with correctly.

You should know the precise cartridge mapper for the CartRegister and CartStatic type to be usable.

So what's the point of the interface if you need to know the details of the underlying type? Couldn't we just use a type assertion?

Yes, but doing it this way helps with the lazy evaluation system used by debugging GUIs. The point of the lazy system is to prevent race conditions and the way we do that is to make copies of system variables before using it in the GUI. Now, because we must know the internals of the cartridge format, could we not just make those copies manually? Again, yes. But that would mean another place where the cartridge's internal knowledge needs to be coded (we need to use that knowledge in the GUI code but it would be nice to avoid it in the lazy system).

The GetRegisters() allows us to conceptualise the copying process and to keep the details inside the cartridge implementation as much as possible.

type CartRAM ¶ added in v0.2.1

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

CartRAM represents a single segment of RAM in the cartridge. A cartridge may contain more than one segment of RAM. The Label field can help distinguish between the different segments.

The Origin field specifies the address of the lowest byte in RAM. The Data field is a copy of the actual bytes in the cartidge RAM. Because Cartidge is addressable, it is also possible to update cartridge RAM through the normal memory buses; although in the context of a debugger it is probably more convience to use PutRAM() in the CartRAMbus interface

type CartRAMbus ¶ added in v0.2.1

type CartRAMbus interface {
	GetRAM() []CartRAM
	PutRAM(bank int, idx int, data uint8)
}

CartRAMbus is implemented for catridge mappers that have an addressable RAM area. This differs from a Static area which is not addressable by the VCS.

Note that for convenience, some mappers will implement this interface but have no RAM for the specific cartridge. In these case GetRAM() will return nil.

The test for whether a specific cartridge has additional RAM should include a interface type asserstion as well as checking GetRAM() == nil

type CartRegisters ¶ added in v0.2.1

type CartRegisters interface {
	fmt.Stringer
}

CartRegisters conceptualises the cartridge specific registers that are inaccessible through normal addressing

type CartStatic ¶ added in v0.2.1

type CartStatic interface {
	fmt.Stringer
}

CartStatic conceptualises the cartridge's static data areas that are inaccessible through normal addressing

type ChipBus ¶

type ChipBus interface {
	// ChipRead checks to see if the chip's memory area has been written to. if
	// it has the function returns true and an instance of ChipData
	ChipRead() (bool, ChipData)

	// ChipWrite writes the data to the chip memory
	ChipWrite(reg addresses.ChipRegister, data uint8)

	// LastReadRegister returns the register name of the last memory location
	// *read* by the CPU
	LastReadRegister() string
}

ChipBus defines the operations for the memory system when accessed from the VCS chips (TIA, RIOT). Only ChipMemory implements this interface.

type ChipData ¶

type ChipData struct {
	// the canonical name of the chip register writter to
	Name string

	// the data value written to the chip register
	Value uint8
}

ChipData is returned by ChipBus.ChipRead()

type DebuggerBus ¶

type DebuggerBus interface {
	Peek(address uint16) (uint8, error)
	Poke(address uint16, value uint8) error
}

DebuggerBus defines the meta-operations for all memory areas. Think of these functions as "debugging" functions, that is operations outside of the normal operation of the machine.

type InputDeviceBus ¶

type InputDeviceBus interface {
	InputDeviceWrite(reg addresses.ChipRegister, data uint8, preserveBits uint8)
}

InputDeviceBus defines the operations for the memory system when accessed from parts of the emulation are peripheral to the operation of the machine. In practice, this includes the front panel in addition to joysticks, etc.