cartridgeloader

Documentation

Overview

Package cartridgeloader is used to specify the cartridge data that is to be attached to the emulated VCS.

When the cartridge is ready to be loaded into the emulator, the Load() function should be used. The Load() function handles loading of data from a different sources. Currently on local-file and data over HTTP is supported.

As well as the filename, the Loader type allows the cartridge mapping to be specified, if required. The simplest instantiation therefore is:

cl := cartridgeloader.Loader{
        Filename: "roms/Pitfall.bin",
}

It is stronly preferred however, that the NewLoader() function is used to initialise the Loader or important fields risk being initialised incorrectly.

The NewLoader() function accepts two arguments. The filename of the cartridge (which might be a HTTP url) and the cartridge mapper. In most cases the mapper will be "AUTO" to indicate that we don't know (or particular care) what the mapping format is.

File Extensions

The file extension of a file will specify the cartridge mapping and will cause the emulation to use that mapping. Most 2600 ROM files have the extension "bin" but sometimes it is necessary to specify explicitly what the mapper is.

The following quoted file extensions are recognised (case insenstive):

Atari 2k		"2k"
Atari 4k		"4k"
Atari 8k		"F8"
Atari 16k		"F6"
Atari 32k		"F4"
Atari 2k (RAM)	"2k+"
Atari 4k (RAM)	"4k+"
Atari 8k (RAM)	"F8+"
Atari 16k (RAM)	"F6+"
Atari 32k (RAM)	"F4+"
CBS				"FA"
Parker Bros		"E0"
M-Network		"E7"
Tigervision		"3F"
Supercharger	"AR"
DF				"DF"
3E				"3E"
3E+				"3E+"
Superbank		"SB"
DPC (Pitfall2)  "DPC"
DPC+			"DP+"
CDF				"CDF" (including CDFJ)

In addition to these above there a three "special" mapping formats. Which aren't really mappers in the normal sense but which will none-the-less trigger a particular cartridge emulation path.

"MP3" and "WAV" indicate that the emulation should use the Supercharger mapper but with the understanding that the data will be loaded from audio data.

"MVC" indicates that the data is a MovieCart stream. Because of the potential size of these files, data is streamed from the file. Also, steaming over HTTP is not yet currently supported.

Finally a file extension of "BIN", "ROM", "A26" will tell the mapping system to "fingerprint" the cartridge data to ascertain the mapping type.

Fingerprinting is not handled by the cartridlgeloader package.

Hash

The Hash field of the Loader type contains the SHA1 value of the loaded data. It is valid after the Load() function has completed successfully. If the field is not empty before Load() is called, that value will be compared with the calculated value. An error is returned if the values differ.

In most cases you wouldn't want to change the Hash field before calling the Load() function but it is sometimes useful to make sure the correct file is being loaded - for example the recorder package uses it to help make sure playback is correct.

The hash value is invalid/unused in the case of streamed data

Streaming

For some cartridge types it is necessary to stream bytes from the file rather than load them all at once. For these types of cartridges the Load() function will open a stream and readbable via the StreamedData field.

The function IsStreaming() returns true if data is to be read from the StreamedData field rather than the Data field.

For streaming to work NewLoader() must have been used to instantiate the Loader type.

Closing

Instances of Loader must be closed with Close() when it is no longer required.

OnInserted

The OnInserted field is used by some cartridges to indicate when the cartridge data has been loaded into memory and something else needs to happen that is outside of the scope of the cartridge package. Currently, this is used by the Supercharder and PlusROM.

Notification Hook

Some cartridge mappers will generate notifications (see notification.Notify type). The NotifcationHook can be specified in order to respond to those events.

Index

• Variables
• type Loader
  • func NewLoader(filename string, mapping string) (Loader, error)
  • func NewLoaderFromEmbed(name string, data []byte, mapping string) (Loader, error)
  • func (cl Loader) Close() error
  • func (cl Loader) IsEmbedded() bool
  • func (cl Loader) IsStreaming() (bool, bool)
  • func (cl *Loader) Load() error
  • func (cl Loader) ShortName() string

Variables

var FileExtensions = [...]string{
	".BIN", ".ROM", ".A26", ".2K", ".4K", ".F8", ".F6", ".F4", ".2K+", ".2KSC",
	".4K+", ".4KSC", ".F8+", ".F8SC", ".F6+", ".F6SC", ".F4+", ".F4SC", ".CV",
	".FA", ".FE", ".E0", ".E7", ".3F", ".UA", ".AR", ".DF", ".3E", ".E3P",
	".E3+", ".3E+", ".EF", ".EFSC", ".SB", ".WD", ".ACE", ".CDF0", ".CDF1", ".CDFJ",
	".CDFJ+", ".DP+", ".DPC", ".CDF", ".WAV", ".MP3", ".MVC",
}

FileExtensions is the list of file extensions that are recognised by the cartridgeloader package.

var NoFilename = errors.New("no filename")

sentinal error for when it is attempted to create a loader with no filename

Types

type Loader

type Loader struct {
	// filename of cartridge to load. In the case of embedded data, this field
	// will contain the name of the data provided to the the
	// NewLoaderFromEmbed() function.
	Filename string

	// empty string or "AUTO" indicates automatic fingerprinting
	Mapping string

	// the Mapping value that was used to initialise the loader
	RequestedMapping string

	// any detected TV spec in the filename. will be the empty string if
	// nothing is found. note that the empty string is treated like "AUTO" by
	// television.SetSpec().
	Spec string

	// expected hash of the loaded cartridge. empty string indicates that the
	// hash is unknown and need not be validated. after a load operation the
	// value will be the hash of the loaded data
	//
	// in the case of sound data (IsSoundData is true) then the hash is of the
	// original binary file not he decoded PCM data
	//
	// the value of Hash will be checked on a call to Loader.Load(). if the
	// string is empty then that check passes.
	Hash string

	// HashMD5 is an alternative to hash for use with the properties package
	HashMD5 string

	// does the Data field consist of sound (PCM) data
	IsSoundData bool

	// cartridge data. empty until Load() is called unless the loader was
	// created by NewLoaderFromEmbed()
	//
	// the pointer-to-a-slice construct allows the cartridge to be
	// loaded/changed by a Loader instance that has been passed by value.
	Data *[]byte

	// for some file types streaming is necessary. nil until Load() is called
	// and the cartridge format requires streaming.
	StreamedData *os.File

	// callback function from the cartridge to the VCS. used for example. when
	// cartridge has been successfully inserted. not all cartridge formats
	// support/require this
	//
	// if the cartridge mapper needs to communicate more information then the
	// action string should be used
	NotificationHook notifications.NotificationHook
	// contains filtered or unexported fields
}

Loader is used to specify the cartridge to use when Attach()ing to the VCS. it also permits the called to specify the mapping of the cartridge (if necessary. fingerprinting is pretty good).

func NewLoader

func NewLoader(filename string, mapping string) (Loader, error)

NewLoader is the preferred method of initialisation for the Loader type.

The mapping argument will be used to set the Mapping field, unless the argument is either "AUTO" or the empty string. In which case the file extension is used to set the field.

File extensions should be the same as the ID of the intended mapper, as defined in the cartridge package. The exception is the DPC+ format which requires the file extension "DP+"

File extensions ".BIN" and "A26" will set the Mapping field to "AUTO".

Alphabetic characters in file extensions can be in upper or lower case or a mixture of both.

Filenames can contain whitespace, including leading and trailing whitespace, but cannot consists only of whitespace.

func NewLoaderFromEmbed

func NewLoaderFromEmbed(name string, data []byte, mapping string) (Loader, error)

NewLoaderFromEmbed initialises a loader with an array of bytes. Suitable for loading embedded data (using go:embed for example) into the emulator.

The mapping argument should indicate the format of the data or "AUTO" to indicate that the emulator can perform a fingerprint.

The name argument should not include a file extension because it won't be used.

func (Loader) Close

func (cl Loader) Close() error

Close should be called before disposing of a Loader instance.

func (Loader) IsEmbedded

func (cl Loader) IsEmbedded() bool

IsEmbedded returns true if Loader was created from embedded data. If data has a length of zero then this function will return false.

func (Loader) IsStreaming

func (cl Loader) IsStreaming() (bool, bool)

IsStreaming returns two booleans. The first will be true if Loader was created for what appears to be a streaming source, and the second will be true if the stream has been open.

func (*Loader) Load

func (cl *Loader) Load() error

Load the cartridge data and return as a byte array. Loader filenames with a valid schema will use that method to load the data. Currently supported schemes are HTTP and local files.

func (Loader) ShortName

func (cl Loader) ShortName() string

ShortName returns a shortened version of the CartridgeLoader filename field. In the case of embedded data, the filename field will be returned unaltered.