Files
CoCo3_Plus_MiSTer/docs/FEATURES.md
T
bholman cb40fed3b9 Introduce Coco 3 Plus for MiSTer
Add original-firmware Sound & Speech, four configurable Multi-Pak sockets,
bounded per-slot ROM allocation and a nine-page menu organized around devices
and media. Repair inherited clock/reset/CPU-memory/video paths and add explicit
conditional external-I/O timing contracts. Preserve native Main startup-file
ordering, saved layouts, stock-core separation and the coco3plus media profile.

Provide native Windows tool downloads, pinned ToolShed ROM assembly, fresh
Quartus builds, functional and fitted timing checks, reviewed release packaging
and passwordless SSH installation with backups. Retain original component
notices, document contribution copyright and keep SSC ROM inputs outside Git.

Validation: Quartus17.0.2 Build602 seed5, zero errors; 15 functional jobs,
368 both-corner timing scopes and eight tooling-integrity checks pass.
The renamed build reaches Disk BASIC, PRINT1+1 returns2 and SSC loads ready.
Physical cold power cycling and conditional board-delay assumptions remain
separate. Full original upstream histories are preserved before this single
consolidated implementation commit.
2026-11-18 16:00:45 -07:00

84 lines
4.9 KiB
Markdown

# Features and implementation
## Four independently configured sockets
The new Multi-Pak configuration separates **what is installed**, **which socket
starts selected**, and **which media is mounted**. Each of four sockets can hold
Empty, ROM file, Floppy, CoCo SDC, Sound & Speech, Orchestra90, Audio expansions,
or RS232. Built-in controllers are singletons: assigning one elsewhere moves
that device rather than inventing another independent controller. The combined
Audio expansions entry preserves simultaneous legacy Orchestra90 and selectable
SSC behavior; it is a convenience combination, not an original physical cartridge.
The router follows independent guest CTS and SCS selectors, with device-qualified
read data, writes and interrupts. Four ROM sockets share a 256 KiB allocation
pool; a single image can use at most 128 KiB. Socket state and banking are private
to each socket. Removing a ROM frees its allocation and suppresses stale autoload.
An oversized/full-pool transfer reports a load error rather than overwriting a
neighbor. Floppy/SDC mounted images follow their controller when it moves slots.
Device changes deliberately cold-restart the guest; media selection does not.
Persisted legacy settings are migrated into a marked four-slot layout. MiSTer
Main's original remembered-file mechanism loads cartridge and SSC files without
custom host software. Early file transfers are staged while initialization holds
reset, then matched against the restored layout before the guest is released.
## Original-firmware Sound & Speech
The SSC implementation includes a TMS7000-family instruction/peripheral engine
for the cartridge's TMS7040 controller, the original 4 KiB controller firmware,
an AY-3-8913-compatible tone/noise/envelope path, an SP0256-compatible speech
sequencer/LPC path using the original 2 KiB AL2 ROM, host interface and cartridge
glue. The original ROM bytes are runtime inputs, not re-created firmware or an
emulator audio recording. Chip implementations are synchronous FPGA logic.
Host status/data behavior, firmware command handshakes, reset/ready transitions,
busy/abort/recovery, firmware instruction behavior and generated samples are
covered by component/integration testing and shared Sound Lab diagnostics.
Normal idle status is FF; it is not evidence of an absent card. No unsupported
cartridge IRQ is invented. Original SSC is mono; its signal is mixed into both
outputs alongside the legacy CoCo audio path. Orchestra90 remains stereo and
can coexist through Audio expansions or distinct assigned sockets.
SSC ROM validity belongs to FPGA power/configuration lifetime. A guest cold boot
or reset does not discard valid runtime ROMs; real core PLL-lock loss does. Strict
file length/address/loader completion checks prevent a partial load from being
reported ready. The OSD shows not ready, ready or error separately.
## SSC and extended-color register ownership
The inherited FPGA extended-color/video-DAC feature uses an address also occupied
by SSC cartridge registers. **Sound & Expansion → Expansion** selects Extended
palette or Sound & Speech. Only the selected implementation owns the shared
register decode. SSC mode also requires an SSC-capable socket assignment; the
menu disables the option and explains the missing assignment otherwise.
The extended palette is an FPGA-specific enhancement, not a claim that an
unmodified physical CoCo3 had that feature. Its original palette/video behavior
is preserved. Orchestra90 does not require enabling the extended-color mode.
Do not infer SSC presence merely from a loaded ROM filename; socket and expansion
ownership determine whether the guest can address it.
The inherited graphics extension provides 256 palette entries with 12-bit RGB
values (four bits per channel) and extended graphics decode. Its VDAC programming
write at FF7E conflicts with SSC; its color lookup and supported pixel-latch
geometry follow `rtl/VDAC.v`, `rtl/VDAC.mif` and `rtl/Mister_Video.v`. This is
preserved implementation, including source-specific low-resolution latch behavior,
not a newly invented standard display mode. Use the original source/manual for
register programming rather than assuming every extended mode is byte-per-pixel.
## Existing functions retained
- Four WD1793-style floppy image mounts and Disk BASIC.
- Two SDC image mounts accepting DSK/VHD plus the existing OS9 floppy mount rows.
- ROM/cartridge loading and banked access within the documented memory pool.
- Cassette CAS playback, rewind, monitoring and recording/export path.
- 512K/1M/2M/16M guest memory choices and existing turbo/autorun controls.
- Aspect ratios, scandoubler effects, artifact choices and CoCo3 LC option.
- USB joystick emulation, swap and mouse as right joystick.
- RS232/UART routing, font loading and debug/Easter Egg controls.
Retained source functionality is not a claim that every optional peripheral,
physical I/O route or large disk format has been tested on the development unit.
See VALIDATION.md for observed coverage and remaining work.