memorymap

Documentation

Overview

Package memorymap facilitates the translation of addresses to primary address equivalents.

Because of the limited number of address lines used by the 6507 in the VCS the number of addressable locations is a lot less than the 16bit suggested by the addressing model of the CPU. The MapAddress() functions should be used to produce a "mapped address" whenever an address is being used from the viewport of the CPU. (Writing to memory from the viewpoint of TIA & RIOT is completely different)

ma, _ := memorymap.MapAddress(address, true)

The second argument indicates if the address is being read or being written to. Some addresses require an additional transformation if they are being read. Again, the details are handled by the function.

During development an internal alternative to the CPUBus was considered (see bus package). The idea was to force use of mapped address when required. This would require new type, MappedAddr, which MapAddress() would return a value of. The MappedCPUBus in turn would expect address values of that type. However, after some experimentation the idea was deemed to be too clumsy and didn't help in clarification. If the memory implementation was required to be more general then it would be a good idea but as it is, it is not necessary.

Index

• Constants
• func IsArea(address uint16, area Area) bool
• func Summary() string
• type Area
  • func MapAddress(address uint16, read bool) (uint16, Area)
  • func (a Area) String() string

Constants

const (
	OriginTIA      = uint16(0x0000)
	MemtopTIA      = uint16(0x003f)
	OriginRAM      = uint16(0x0080)
	MemtopRAM      = uint16(0x00ff)
	OriginRIOT     = uint16(0x0280)
	MemtopRIOT     = uint16(0x0297)
	OriginCart     = uint16(0x1000)
	MemtopCart     = uint16(0x1fff)
	OriginAbsolute = uint16(0x0000)
	MemtopAbsolute = uint16(0xffff)
)

The origin and memory top for each area of memory. Checking which area an address falls within and forcing the address into the normalised range is all handled by the MapAddress() function.

Implementations of the different memory areas may need to drag the address down further into the the range of the memory array. This is best done with (address^origin) rather than subtraction.

const (
	OriginCartFxxxMirror = uint16(0xf000)
	MemtopCartFxxxMirror = uint16(0xffff)
)

Cartridge memory is mirrored in a number of places in the address space. The most useful mirror is the Fxxx mirror which many programmers use when writing assembly programs. The following constants are used by the disassembly package to reference the disassembly to the Fxxx mirror.

Be extra careful when looping with MemtopCartFxxxMirror because it is at the very edge of uint16. Limit detection may need to consider the overflow conditions.

const (
	MaskCart      = MemtopCart
	MaskReadRIOT  = uint16(0x0287)
	MaskWriteRIOT = MemtopRIOT
	MaskRAM       = MemtopRAM
	MaskReadTIA   = uint16(0x000f)
	MaskWriteTIA  = MemtopTIA
)

The masks to apply to an address to bring any address into the primary range. Prefer to use MapAddress() for ease of use.

const (
	CartridgeBits = OriginCart ^ MemtopCart
)

CartridgeBits identifies the bits in an address that are relevant to the cartridge address. Useful for discounting those bits that determine the cartridge mirror. For example, the following will be true:

0x1123 & CartridgeBits == 0xf123 & CartridgeBits

Alternatively, the following is an effective way to index an array:

addr := 0xf000
mem[addr & CartridgeBits] = 0xff

In the example, index zero of the mem array is assigned the value 0xff.

const Memtop = uint16(0x1fff)

Memtop is the top most address of memory in the VCS. It is the same as the cartridge memtop.

Functions

func IsArea

func IsArea(address uint16, area Area) bool

IsArea returns true if the address is in the specificied area.

func Summary

func Summary() string

Summary returns a single multiline string detailing all the areas in memory. Useful for reference.

Types

type Area

type Area int

Area represents the different areas of memory.

const (
	Undefined Area = iota
	TIA
	RAM
	RIOT
	Cartridge
)

The different memory areas in the VCS.

func MapAddress

func MapAddress(address uint16, read bool) (uint16, Area)

MapAddress translates the address argument from mirror space to primary space. Generally, an address should be passed through this function before accessing memory.

func (Area) String

func (a Area) String() string