212 lines
7.1 KiB
Plaintext
212 lines
7.1 KiB
Plaintext
|
|
This describes the cartridge interface design for VCC
|
|
|
|
---
|
|
|
|
# VCC Cartridge Types
|
|
|
|
VCC emulates the physical cartridges that could be plugged into the side expansion slot
|
|
of a CoCo 3 or into a MultiPak Interface. VCC supports three main categories of cartridges:
|
|
|
|
---
|
|
|
|
## 1. ROM Cartridges
|
|
|
|
ROM cartridges contain only read-only memory and the minimal hardware needed to expose that
|
|
memory to the CoCo 3.
|
|
|
|
**Characteristics:**
|
|
|
|
- Typically contain 6809 or 6309 executable code.
|
|
- The CoCo reads data directly from mapped ROM addresses.
|
|
- Some cartridges support bank switching by writing to I/O ports.
|
|
- In VCC, all ROM banking logic is implemented inside the emulator itself.
|
|
- ROM cartridges require no host-side code.
|
|
- They are stored as simple binary files.
|
|
- Some ROM files include headers or signatures to indicate special mapping or banking behavior.
|
|
- Most common ROM cartridges were 16 KB or smaller and mapped at `0xC000` in ROM mode.
|
|
|
|
---
|
|
|
|
## 2. Hardware Cartridges
|
|
|
|
Hardware cartridges contain actual devices, such as:
|
|
|
|
- Disk controllers
|
|
- Sound synthesizers
|
|
- RS-232 interfaces
|
|
- Additional microprocessors
|
|
- Often, onboard ROM
|
|
|
|
These cartridges require host-side x86 code to emulate their hardware behavior.
|
|
|
|
**In VCC:**
|
|
|
|
- Hardware cartridges are implemented as **Windows DLLs**.
|
|
- VCC identifies them by checking for the `MZ` signature at the start of the file.
|
|
- Hardware DLL's must export the PakInitialize call to be valid
|
|
- ROM data for these cartridges is usually stored separately, though this is not required.
|
|
- Some hardware cartridges can load multiple ROMs and switch between them under program control.
|
|
- The DLL is responsible for loading and managing these ROMs.
|
|
- The CoCo communicates with the emulated hardware by reading and writing specific I/O ports.
|
|
- Hardware cartridges may generate interrupts or output audio through a dedicated sound channel.
|
|
- Hardware cartridges cannot load other hardware cartridges.
|
|
|
|
---
|
|
|
|
## 3. MultiPak Cartridge (MPI)
|
|
|
|
MultiPak is a special type of hardware cartridge, not really a true cartridge, it is a
|
|
bus expansion that acts as hosts for other hardware cartridges.
|
|
|
|
**Capabilities:**
|
|
|
|
- MultiPak Cartridge DLL must export the init MPI call to be valid
|
|
- Provide multiple cartridge slots.
|
|
- Contains no ROM of it's own
|
|
- Allow slot selection through UI controls or programmatically.
|
|
|
|
**VCC support:**
|
|
|
|
- VCC currently emulates the original Radio Shack MultiPak Interface.
|
|
- Multipak can only be inserted Coco slide slot, not into another multipak.
|
|
- Third-party MultiPak-style devices also exist, including:
|
|
- Two-slot versions
|
|
- Hobbyist designs supporting up to eight slots
|
|
|
|
---
|
|
|
|
# Cartridge Loader: Cartridge Type Identification Logic
|
|
|
|
The cartridge loader determines the cartridge type using the following sequence:
|
|
|
|
1. **Check if the file can be read**
|
|
- If it cannot be read, the cartridge is **not loadable**.
|
|
|
|
2. **Check if the file is a DLL**
|
|
- If it is *not* a DLL, the cartridge is a **ROM Cartridge**.
|
|
|
|
3. **Check if the DLL exports `InitCart`**
|
|
- If it does *not*, the cartridge is **not loadable**.
|
|
|
|
4. **Check if the DLL exports PakGetCapabilities**
|
|
- If it does not, the cartridge is CART_TYPE_GENERIC
|
|
|
|
5. Continue with loading and initialization
|
|
|
|
---
|
|
|
|
#Cartridge Exports
|
|
|
|
DLL's can export any of the following calls
|
|
|
|
Initiate pack (REQUIRED)
|
|
PakInitialize (SLotId, settings_path, hVccWnd, &callbacks);
|
|
|
|
Retrieve cart menu item
|
|
PakGetMenuItem(item, index);
|
|
|
|
Get cart capabilities (PROPOSED)
|
|
PakGetCapabilities (void);
|
|
|
|
Terminate pack, prepare for DLL unload
|
|
PakTerminate ()
|
|
|
|
Get pack name
|
|
PakGetName (name, buf_size)
|
|
|
|
Get pack ID
|
|
PakGetCatalogId (catalogId, buf_size)
|
|
|
|
Get pack description
|
|
PakGetDescription (Description, buf_size)
|
|
|
|
Reset the pack
|
|
PakReset ()
|
|
|
|
Horizontal sync occurred
|
|
PakProcessHorizontalSync ()
|
|
|
|
Get pack status line text
|
|
PakGetStatus (Status, buf_size)
|
|
|
|
Write I/O port
|
|
PakWritePort (Port, data)
|
|
|
|
Read I/O port
|
|
unsigned char PakReadPort (Port)
|
|
|
|
Read ROM byte
|
|
unsigned char PakReadMemoryByte (Address)
|
|
|
|
Sample audio line
|
|
unsigned short PakSampleAudio ()
|
|
|
|
A hardware pack menu item was clicked
|
|
PakMenuItemClicked (menu_item_id)
|
|
|
|
---
|
|
|
|
#Callbacks
|
|
|
|
There are two ways a cartridge can initiate host actions:
|
|
|
|
1) Notifications initiated by cartridge UI events like adding menu items or inserting
|
|
cartridges in slots. These are asyncronous and can rely on DLL exports for details.
|
|
The mechanism for these is Vcc's main window message loop. The window handle (hVccWnd)
|
|
has been added to PakInitialize() for this purpose. Two notification messages are
|
|
defined, one to initiate a VCC reset and another to initiate cartridge menu rebuilds.
|
|
|
|
2) Callbacks initiated by 6x09 code running inside the CPU loop such as asserting
|
|
interrupts, cart lines, or reading and writing memory to handle DMA requests. These
|
|
are syncronous and must return quickly to not affect emulator timing. Callbacks are
|
|
determined by Coco3's physical bus and are not likely to change. There are four
|
|
callbacks:
|
|
|
|
void assert_cartridge_line (SlotId, line_state)
|
|
void assert_interrupt (SlotId, interrupt, interrupt_source)
|
|
void write_memory_byte (SlotId, value, address)
|
|
unsigned char read_memory_byte (SlotId, unsigned short address)
|
|
|
|
SlotId is used by the MPI to filter assert_cartridge_line. DLL's are passed their slot
|
|
location in PakInitialize().
|
|
|
|
---
|
|
|
|
#Proposed New Design Philosophy For The MPI (under consideration)
|
|
|
|
VCC and forks of VCC use run-time loading and unloading of dynamic libraries to simulate
|
|
the inserting and removing of Cartridges.
|
|
|
|
A special "cartridge" is the Multipak MPI. On a physical Coco the MPI it is not actually
|
|
a cartridge. It is more accurately an extension of the bus.
|
|
|
|
The pakinterface loads and unloads cartridges. So does the MPI. If both MPI and pakinterface
|
|
call cartridge DLLs directly there are now two modules, VCC and MPI, that need to know about
|
|
cartridge lifetimes, handles, exports, and inports. All loading and unloading of carts belongs
|
|
in one place and that place is the PakInterface part of VCC main.
|
|
|
|
If slot management is moved to the Pakinterface the logic that controls the CTS and SCS and
|
|
the management of saved slot content settings must move too. The pakinterface must share this
|
|
information with the MPI DLL which becomes purely a user interface.
|
|
|
|
The pakinterface slot management concept:
|
|
|
|
- The pakinterface maintains a list indexed by slot number of loaded cartridges.
|
|
|
|
- Slots are numbered 0-4. Slot 0 is the Boot slot. Slots 1-4 loaded if MPI is in the Boot slot.
|
|
|
|
- The pakInterface routes I/O to slots per CTS/SCS using existing capability / callcacks
|
|
|
|
- The pakinterface saves slot content to settings.
|
|
|
|
- Any change to current CTS triggers a reset. This is detected and effected by the pakinterface
|
|
Reset stops the CPU, unloads all cartridges, reloads the basic rom, reloads cartridges
|
|
per settings, and then restarts the CPU.
|
|
|
|
- MPI sends changes to startup CTS/SCS via a notification message. Startup CTS/SCS does not
|
|
affect the running CPU, a reset is required for them to take effect.
|
|
|
|
- The MPI requests cartridge loads / unloads by sending messages to WinMain.
|
|
|