Files
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

99 lines
10 KiB
Markdown

# Fixes and engineering changes
This inventory describes the delta from upstream commit
`8b8cf72d1fb4de1d05345de8d5b92ec2d500fcd2`. It distinguishes repairs to inherited
logic from new features and defects found while integrating those features.
The checks below establish their stated scopes; they do not turn source
inspection into a claim of a reproduced field failure.
## Inherited clock, reset and memory paths
| Area and problem | Change and relevant source | Verification and limits |
|---|---|---|
| FDC/SDC mount metadata used transfer events as clocks, leaving generated-clock and phase hazards. | Capture mount strobes/metadata synchronously, classify on a subsequent phase and present stable consumer inputs. `rtl/fdc.sv`, `rtl/sdc_top.sv`, `rtl/sdc.sv`, top-level bindings. | Interface/phase simulations and fitted setup/hold. A mounted DSK still needs guest-format compatibility checks. |
| UART timing used independently derived fabric clocks and incompletely coordinated resets. | Use source-clock enables and explicit global/software reset release; preserve UART bit rate and register behavior. `rtl/UART_6551/` and core serial bindings. | Serial/reset component regressions and UART fitted paths. Physical RS232/GPIO electrical routing is separate. |
| NMI pending/mask state used a generated sampling clock and asynchronous clear path. | Move pending sampling/clear into the master domain, preserve sample ordering and mask/shadow priority, clear pending state on warm reset. `rtl/mc6809glb/mc6809glb.v`. | CPU/NMI regressions and both-corner NMI paths. The S-register change heuristic is retained; this is not a claim of a new fully cycle-exact 6809. |
| Reset sequencing was timed through a signal treated as a clock, with high-fanout cross-phase release. | Separate reset requests from synchronized consumer releases at the 57/114 MHz and opposite-edge boundaries; preserve original startup counters and peripheral-before-CPU order. `rtl/coco3fpga.sv`, disk wrappers and SDC/WD logic. | Extracted actual reset chains, complete reset timing scopes, negative control for unsupported consecutive enables. No blanket false-path waiver replaces release timing. |
| CPU-to-SDRAM requests/completions crossed phase boundaries without explicit registered contracts. | Add `rtl/cpu_sdram_bridge.sv`; register request, address/data/control and completion observation in their proper phases. Preserve the proven nonconsecutive CPU-enable contract. | Protocol, actual-controller, boot-control and delayed-data benches; fitted bridge/control/CPU checks. Simulation adaptations preserve logic but do not model physical SDRAM pins. |
| Keyboard/control and CPU-visible peripheral values could be observed on the wrong consumer phase. | Capture keyboard flags and control/request boundaries, align data-ready observation and SDC CPU buffer access with actual inverted wrapper clocks. Keep the original WD direct read path. | Exhaustive keyboard decode/phase comparison, peripheral and disk-buffer tests with the real wrapper inversion. A passing leaf-only RAM test was insufficient and was replaced. |
| Video address arithmetic extended into the SDRAM ACTIVE decision, creating an inherited negative setup path. | Snapshot the video address before ACTIVE; retain the existing two-word read burst and wrap/guard semantics. `rtl/sdram/sdram2.sv`. | Original-versus-candidate fetch comparison and corrupted-address negative control, plus fitted snapshot/activation paths. No video-address false path is added. |
| SDRAM startup/refresh/return behavior lacked an explicit external timing contract. | Match refresh cadence, startup/precharge recovery and return capture to the documented controller/device profile; phase the forwarded clock through the configured DDIO path. | Command scheduler, delayed CPU/video data models and pin-level STA for the conditional Alliance -7 profile. Unknown module speed/PCB delay remains an assumption. |
| Pixel, audio and board-I2C boundaries were incompletely modeled in STA. | Add source-matched pixel/forwarded clocks and external input/output budgets; constrain both HDMI video clock modes, audio transport and MCP I2C. Preserve bounded I2C protocol timing. `external-io.sdc`, `CoCo3.sdc`, framework audio/I2C bindings. | Actual divider/duty negative control, audio serialization, delayed I2C and 48 substantive external scopes. Optional HPS/muxed/async pins are classified separately, not silently declared timed. |
CPU multicycle constraints are restricted to source-qualified register roles and
proven enables. Unqualified state remains single-cycle. Reset and SDRAM fixes
retain explicit phase/latency contracts; adding an extra return cycle merely to
improve fit is not acceptable.
## New SSC implementation and integration corrections
These are new hardware functions, not fixes to a pre-existing upstream SSC core.
`rtl/ssc/` implements the host bridge, cartridge glue, TMS7000-family controller,
AY-3-8913 and SP0256 speech path. `rtl/coco3fpga.sv` supplies CPU decode/audio;
`CoCo3.sv` supplies menu/runtime ROM input and actual-PLL reset wiring.
- **Runtime ROM lifetime:** guest reset originally risked clearing loaded ROM
validity. Tie cartridge power reset to the actual core PLL-lock release chain,
preserving valid firmware across guest reset/cold boot. Both original ROMs must
pass the strict complete-load contract before ready is asserted.
- **Shared-address ownership:** SSC must replace the inherited video-extension
register decode when selected. Gate both sides, qualify reads before the
ordinary bus mux, and disable SSC selection when no capable socket exists.
- **Command/CPU phase ordering:** latch host transactions and firmware-visible
transitions on explicit enables; preserve data/status ordering and reset/abort
recovery. Never interpret idle FF as a missing cartridge.
- **Original firmware execution:** instruction, immediate-operand, flag, stack,
timer/interrupt and peripheral semantics follow the actual firmware and chip
documentation/reference models. In particular FF operand handling is exercised
by dedicated regressions. The implementation runs the original bytes rather
than substituting host-side command responses.
- **Speech and audio completion:** integrate sequencer/ROM/LPC filtering and AY
tone/noise/envelope output into the legacy audio mix. Busy/readiness must return
to idle after normal completion or deliberate abort/reset. Mono SSC does not
replace Orchestra90's stereo route.
Original-firmware integration, chip/component fixtures, fitted live-chip path
audits and Sound Lab listening/transaction checks provide complementary evidence.
Human listening confirms audibility; it is not an automated waveform-equivalence
claim for all possible cartridge commands.
## Four-slot integration corrections
| Defect found during development | Final behavior and check |
|---|---|
| HPS decode/RAM allocation on opposing edges left an inadequate transfer path. | Register incoming transfer metadata/data before allocation/writes. Pool tests and fitted MPI paths check the full stage. |
| Removal/failure overlap could retain allocation or active autoload state. | Removed sockets free blocks; failed/new downloads cannot corrupt neighboring allocations. Concurrent removal/failure regression checks this explicitly. |
| Duplicate built-in assignment could create ambiguous routing. | Most recently edited socket wins; singleton devices move. Combined Audio can leave its other component in the old socket. Exhaustive router/config fixtures exercise deterministic normalization. |
| Main sends remembered files before restoring saved layout. | Stage early slot ROMs while Main holds reset, then accept against restored layout. Testing only a default layout missed the Slot4 case; native parser and composed startup fixtures now include non-default layouts. |
| Normalization acknowledgement could clear Main's initialization reset too early. | Defer publishing migration status until Main's final release. Staging files alone did not fix this second initialization ordering issue. The old behavior is a negative-control failure. |
| Long labels truncated the usable OSD rows. | Use short labels within the existing OSD width, retain nine stable pages and explicitly show pool limits, assignment requirements and readiness. Native Main menu parser checks every option's status-bit contract and conditional row visibility. |
The new router keeps CTS/SCS independent and qualifies read/IRQ/bank behavior
against the effective socket. Tests extract the actual top/core bindings rather
than checking only an isolated idealized router. Native menu/startup tests use
pinned original Main functions; no custom Main binary is required.
## Packaging and startup corrections
The launcher and embedded display identity are Coco 3 Plus; native MGL `setname` makes settings/media
use `coco3plus` consistently. Hidden RBF storage keeps the stock core separate.
Remembered-file records must use the canonical folder and accept the existing
absolute/relative Main path conventions. Old-prefix replacements must respect
folder boundaries, not accidentally rewrite a similarly named folder.
The installer passes raw structured SCP arguments. Embedding shell quote marks
inside a modern SFTP path can create literal quotes or fail a spaced launcher
upload; shell quoting is reserved for the remote shell script itself. It stages
and checks files before activation, preserves saved settings, and records rollback.
These are deployment fixes, not defects attributed to upstream FPGA/Main logic.
## Corrections that were test issues, not core bugs
Idle SSC status FF is expected. Disk BASIC direct-mode `INPUT#` raises ID
(illegal direct); stored-program reads succeed. A panic attempted after speech
already completed cannot prove active abort recovery. Mouse JOYSTK queries must
use the configured port and a progressing BASIC loop. These observations led to
corrected tests, not speculative RTL edits. An intermediate SDRAM candidate with
an unnecessary extra READY/return stage produced a green-@ startup failure; it
was rejected and the first-beat contract restored before qualification.