Publish VCC Plus OSS source distribution for 3.6.2 build 60
This commit is contained in:
commit
c652a5276d
1192 files changed
+272368
No files matched your search
@@ -0,0 +1,211 @@
|
||||
|
||||
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.
|
||||
|
||||
Reference in new issue
Block a user