
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.

