bus

Documentation

Overview

Package bus defines the memory bus concept. For an explanation see the memory package documentation.

Package bus defines the memory bus concept. For an explanation see the memory package documentation.

Index

• type CPUBus
• type CPUBusZeroPage
• type CartRAM
• type CartRAMbus
• type CartRegisters
• type CartRegistersBus
• type CartStatic
• type CartStaticBus
• type ChipBus
• type ChipData
• type DebugBus
• type InputDeviceBus

Types

type CPUBus

type CPUBus interface {
	Read(address uint16) (uint8, error)
	Write(address uint16, data 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

Addresses should be mapped to their primary mirror when accesses the RIOT, TIA or RAM; and should be unmapped when accessing cartridge memory (some cartridge mappers are sensitive to which cartridge mirror is being used)

type CPUBusZeroPage

type CPUBusZeroPage interface {
	// 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)
}

type CartRAM

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

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

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

type CartRegisters interface {
	fmt.Stringer
}

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

type CartRegistersBus

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

CartRegistersBus defines the operations required for a debugger to access the registers in a cartridge.

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

You should know the precise cartridge mapper for the CartRegisters 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 CartStatic

type CartStatic struct {
	Label string
	Data  []uint8
}

CartStatic conceptualises tatic data areas that is inaccessible through. Of the cartridge types that have static areas some have more than one static area.

Unlike CartRAM, there is no indication of the origin address of the StaticArea. This is because the areas are not addressable in the usual way and so the concept of an origin address is meaningless and possibly misleading.

type CartStaticBus

type CartStaticBus interface {
	fmt.Stringer

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

CartStaticBus defines the operations required for a debugger to access the static area of a cartridge.

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 DebugBus

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

DebugBus 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.