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.
This commit is contained in:
bholman committed 2026-11-18 16:00:45 -07:00
1 parent 8b8cf72d1f
commit cb40fed3b9
126 files changed
+12795 -528

No files matched your search

+98
View File
@@ -0,0 +1,98 @@
# 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.
+129
View File
@@ -0,0 +1,129 @@
# Windows build and validation
## Required tools
Use 64-bit Windows, Git for Windows and Python **3.10 or newer**. Scripts use the
Python standard library. PowerShell wrappers accept `-Python <full-path>` when
`python` is not on PATH. All commands below run from the repository root.
Install **Quartus Prime Lite 17.0.2, Build 602**, including Cyclone V device files.
The device is **5CSEBA6U23I7**. The project originated in Quartus 17.0; its pinned
settings record 17.0.2. Install the 17.0 base package and matching device package,
then the 17.0 Update 2 package when using the separate installers. Check:
```powershell
& C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sh.exe --version
```
Obtain installers through the [official Altera software download center](https://www.altera.com/downloads).
See also [MiSTer's compilation guidance](https://mister-devel.github.io/MkDocs_MiSTer/developer/compile/).
Setup does not silently install Quartus, accept its license or select a newer IP
generator. Other Quartus versions require separate baseline/timing validation.
## Download public build dependencies
```powershell
.\windows\Setup-Tools.ps1
```
This downloads native Windows x64 [LWTOOLS 4.25](https://www.lwtools.ca/releases/lwtools/),
eight pinned [ToolShed cocoroms](https://github.com/nitros9project/toolshed/tree/3667a41c9605b7fcb150eace29cc7f42d460be1a/cocoroms)
source files and four pinned MiSTer Main source files used only by parser tests.
Archives, extracted files and individual source files are checked against
`tools/toolchain.json` and `tools/cocoroms.json`. Existing changed downloads are
rejected, not silently replaced. `.cache`, `.tools` and `.deps` are ignored.
No SSC firmware, software library or emulator source is fetched.
## Assemble boot ROMs
```powershell
.\windows\Build-ROMs.ps1
```
The native LWASM recipe follows ToolShed's dependency order: BASIC 1.3,
`dumpcb_equates`, Extended BASIC 1.1, `dumpecb_equates`, Disk BASIC 1.1 with
`noindex0tonone`, then the CoCo3 ROM. Four output SHA-256 values must match before
`boot0.rom` and `boot1.rom` are staged in `build/roms`. The receipt records every
command and input/output identity. No C compiler or CMOC is required.
The assembly rebuild is reproducible; availability of source is not a blanket
permission to redistribute the resulting third-party ROMs. See LICENSING.md.
The ToolShed tree inspected contains SSC documentation but no original SSC
TMS7040 or SP0256 ROM source. Those chips cannot be reconstructed with this
6809 assembly recipe; supply their verified originals as described in roms/README.md.
## Compile the FPGA
```powershell
.\windows\Build-FPGA.ps1 -QuartusSh C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sh.exe
```
This makes a fresh `build/fpga/project` copy, records individual source hashes,
uses the committed seed 5 and original build-ID flow, and invokes the native
Quartus compile. It leaves checked-in source/IP untouched. Logs, reports, bitstream
and `build.json` remain under `build/fpga`. Success requires a generated RBF,
nonnegative timing-summary slack and unchanged input hashes. Warning details
remain in the native log; success is not a claim that no warnings occurred.
Never compile in the source checkout or let the GUI replace HDL assignments.
New HDL belongs in `files.qip`; add it and any new source/IP/data dependencies to
the maintained `tools/project_inputs.json` inventory too. The builder rejects
unlisted HDL/constraint/IP inputs in the source directories before copying.
`validation/source-import.json` is historical provenance, not the build inventory.
The receipt derives the seed from the actual single QSF assignment.
Generated caches/IP upgrades stay in build copies.
Outputs are preserved: use `-Output build/fpga-next` for another build, with matching
`--build` arguments when packaging/auditing it, rather than deleting prior results.
## Functional and detailed timing checks
Optional HDL tooling can be downloaded with:
```powershell
.\windows\Setup-Tools.ps1 -IncludeSimulator
.\windows\Test.ps1
```
The pinned OSS CAD Suite supplies Icarus Verilog. The native Main parser fixtures
also need Visual Studio 2022 C++ Build Tools (MSVC and Windows SDK), or a native
C++17 compiler on macOS/Linux. These fixtures compile selected original parser
functions with mocked file/transport calls; they do not build or replace Main.
Supply an existing suite with `Test.ps1 -Suite <oss-cad-suite-folder>`.
`scripts/run_regressions.py` runs 15 independent jobs: MPI modules and actual core
bindings, original-firmware SSC integration, memory/reset/keyboard/peripheral
phase checks, SDRAM command/delayed-data tests, audio/pixel/I2C contracts, native
startup/menu parsing and original-versus-new video fetch. Several include
deliberately faulty negative controls. Complete repeat runs require a new
`--output build/<name>` directory. SSC integration requires the ignored chip ROMs.
After a full fit, run detailed path audits with:
```powershell
python tools/audit_timing.py --quartus C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sta.exe
```
The audits inspect the fitted MPI, CPU/reset, NMI, UART, video, SSC and conditional
external-I/O profile at both timing corners. Empty reports are never treated as
substantive passes; synchronous-only recovery/removal reports may be empty where
explicitly documented. These checks do not remove the remaining physical-board
assumptions listed in docs/VALIDATION.md.
## Release/install
```powershell
.\windows\Package-Release.ps1
.\windows\Install-MiSTer.ps1 -Release dist\coco3plus -Load
```
Packaging verifies the RBF and boot/SSC ROM identities, writes a manifest and
SHA256SUMS, and creates a copyable `fat/` overlay. No files from build caches or
source-reference downloads are installed. Packaging requires reviewed changes
committed; corresponding source comes only from that committed Git tree, never
untracked local files. `-PublicPackage` omits all separately obtained/assembled ROMs
and produces a core/source distribution requiring user ROM preparation. It is
distinct from a complete local install package. Details: docs/INSTALL.md.
Portable Python entry points under tools/ support native macOS/Linux tooling
where available. Quartus itself has no native macOS build; use the Windows or
supported Linux toolchain. The automatic prebuilt-tool download is Windows x64.
+83
View File
@@ -0,0 +1,83 @@
# 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.
+105
View File
@@ -0,0 +1,105 @@
# Install and operate Coco 3 Plus
## Existing MiSTer, passwordless SSH
Have a working MiSTer installation and key-based SSH login before running the
installer. On Windows OpenSSH is available as an optional Windows feature. Test:
```powershell
ssh root@YOUR-MISTER
```
Establish the correct host fingerprint and public-key login through your normal
SSH setup. The installer uses `BatchMode=yes` and `StrictHostKeyChecking=yes`:
it does not request/store passwords or accept unknown host keys silently.
The default Unix user is root, as on standard MiSTer. Another account must already
have permission to write the FAT volume and issue MiSTer commands.
Build ROMs/FPGA per BUILD_WINDOWS.md. Put the two separately obtained chip ROMs
in `roms/ssc`; packaging checks their exact size and SHA-256 before remote writes.
They remain ignored by Git. Then save guest work, close files and stop disk
activity. Installation returns to MENU, so the current guest session is ended.
```powershell
.\windows\Install-MiSTer.ps1 -Load
# Or specify the address:
.\windows\Install-MiSTer.ps1 -HostName YOUR-MISTER -Load
```
If no address is given, the script prompts for one. It first validates every
local input, then checks remote access, stages files, verifies remote SHA-256,
returns to MENU, backs up replaced files, copies the overlay, checks installed
hashes, syncs the volume and optionally loads the launcher. A timestamped receipt
in ignored dist storage records the device and rollback path. It does not change
accounts, networking, Samba, the Linux installation or nonvolatile FPGA storage.
Only the Plus launcher, its uniquely addressed RBF, two boot ROMs and optional
SSC ROM/path records are installed. The stock core and other guest media remain.
Existing `coco3plus_v51.CFG` is kept. First installs get Audio expansions / SDC /
ROM / Floppy, startup Slot4, 512K, and Sound & Speech enabled when ROMs are supplied.
Existing users retain their own layout and expansion selection.
`-WithoutSSC` creates a base-only package without chip ROMs/path records. It does
not delete SSC files already installed on a device. Its
fresh configuration selects Extended palette. SSC remains unavailable until
valid ROMs are supplied and its cartridge/mode is selected.
## Files and copying instead of SSH
`Package-Release.ps1` writes `dist/coco3plus/fat` and the matching
`dist/coco3plus.zip` archive. The release also includes a corresponding-source
ZIP, file checksums, notices and manifest. The FAT overlay contains:
```text
fat/
_Computer/Coco 3 Plus.mgl
_Computer/.coco3plus/<RBF-hash-prefix>/coco3plus.rbf
games/coco3plus/boot0.rom
games/coco3plus/boot1.rom
games/coco3plus/pic-7040-510.bin (separate supplied input)
games/coco3plus/sp0256-al2.bin (separate supplied input)
config/coco3plus.f4, coco3plus.f5 (when SSC included)
config/coco3plus_v51.CFG (new installs only)
```
Power off MiSTer before removing its card. Copy the **contents** of fat/ to its
data-volume root, including `_Computer`'s hidden `.coco3plus` child. Back up collisions
and skip the supplied CFG when one already exists. Preserve the manifest next
to your release archive. Copying this folder onto an unprepared card does not
install Linux or make it bootable.
Guest `.DSK`, `.VHD`, `.CCC`, `.ROM`, `.BIN` and `.CAS` files belong in
`games/coco3plus` or subfolders. A software library is optional and is not silently
downloaded or redistributed by setup. Keep a pristine diagnostic disk and use
writable copies for saved results.
## Public source/core packages
Local complete packages can contain your own ROM inputs and must not be published
as though ignored files were automatically excluded from ZIPs. Use
`Package-Release.ps1 -PublicPackage -Output dist/coco3plus-public` for a source/core
artifact that omits all boot and SSC ROMs. Supply the required ROMs before manual
copy/launch. The SSH installer rejects this incomplete-ROM package and directs
you to make a complete local package from your own verified inputs.
## First launch and recovery
Choose Computer → Coco 3 Plus. It should reach Disk Extended Color BASIC.
`PRINT 1+1` should print 2. F12 → Sound & Expansion reports Sound & Speech ready
after its original ROMs load automatically. F12 → Cartridges & Multi-Pak controls
the four sockets and startup slot. F12 → Floppy Disks mounts images without
changing the layout. Changing socket devices restarts the guest.
The MGL uses native `setname=coco3plus`, so settings and remembered files use the
same canonical namespace. The RBF also identifies itself as **Coco 3 Plus**, so
welcome/help strings no longer expose the retired development name. The native
profile override remains `coco3plus`; changing the display identity does not
require abandoning the existing saved settings or media.
For rollback, return to MENU and restore `_Computer/Coco 3 Plus.mgl` from the
receipt's remote backup directory. Its previously addressed RBF remains in place.
Restore backed-up boot/SSC/path files if those inputs also need rollback. Existing
saved CFG was not overwritten. On a first installation, select the preserved
stock CoCo3 entry to use the original environment. Keep backup/staging folders
until physical cold-start and audio checks pass; failed installs retain their
staging evidence instead of deleting it automatically.
+105
View File
@@ -0,0 +1,105 @@
# Menu tree and operating guide
Select **Computer → Coco 3 Plus**, then press F12 for its core menu. Escape/F12
closes the OSD; Left returns from a page. MiSTer's own system menu supplies core
selection, configuration saving and other host-wide controls. The following tree
is the Plus `CONF_STR` organization; conditional rows depend on assigned devices.
```text
Coco 3 Plus
├─ Cartridges & Multi-Pak
│ ├─ Startup slot: Slot 1 / Slot 2 / Slot 3 / Slot 4
│ ├─ Slot 1: Empty / ROM file / Floppy / CoCo SDC / Sound & Speech /
│ │ Orchestra90 / Audio expansions / RS232
│ │ └─ Slot 1 ROM (when that socket provides program ROM)
│ ├─ Slot 2: same device choices; Slot 2 ROM
│ ├─ Slot 3: same device choices; Slot 3 ROM
│ ├─ Slot 4: same device choices; Slot 4 ROM
│ ├─ ROM pool: 256K total; Max ROM: 128K per slot
│ └─ ROM load error: size/full (only on error)
├─ Floppy Disks
│ ├─ Drive 0: DSK
│ ├─ Drive 1: DSK
│ ├─ Drive 2: DSK
│ └─ Drive 3: DSK
├─ CoCo SDC
│ ├─ SDC Drive 0: DSK / VHD
│ ├─ SDC Drive 1: DSK / VHD
│ └─ OS9 floppy mounts: /d0 / /d1 / /d3 / /d4 (DSK)
├─ Sound & Expansion
│ ├─ Expansion: Extended palette / Sound & Speech
│ ├─ Assign SSC in Multi-Pak (when no SSC-capable socket exists)
│ ├─ Sound & Speech not ready / ready / error
│ ├─ Orchestra90 stereo enabled (when assigned)
│ └─ Audio = SSC + Orchestra90 (explanation)
├─ Cassette
│ ├─ Load Cassette: CAS
│ ├─ Stop & Rewind
│ ├─ Monitor Tape Sound: No / Yes
│ ├─ Save Cassette: CAS
│ └─ Transport: Playback / Rewind / Record
├─ Machine
│ ├─ Memory Size: 512K / 1M / 2M / 16M
│ ├─ Force Turbo: No / Yes
│ ├─ Turbo Speed: CoCo Ctrl / 0.89 / 1.78 / 2.86 / 3.58 / 7.16 / 9.54 MHz
│ ├─ Auto Run: Off / DOS / AUTO.BAS
│ ├─ Cold Boot
│ └─ Reset
├─ Display
│ ├─ Aspect ratio: Original / Full Screen / Wide / [ARC1]
│ ├─ Scandoubler Fx: None / HQ2x / CRT 25% / CRT 50% / CRT 75%
│ ├─ CoCo3 LC: Yes / No-(SG6=Yes)
│ ├─ Artifact Type: MESS / Simple / NONE
│ └─ Artifact Color Set: 0 / 1
├─ Input
│ ├─ D-Pad Joystick emu: No / Yes
│ ├─ Swap Joysticks: Off / On
│ └─ Mouse as right joystick: Off / On
└─ Advanced
├─ Load COCO Font: BIN
├─ Swap MiSTer Uart: RS CART / Default
├─ Swap Uart to IO: RS IO / MiSTer
├─ Display Debug: Off / On
└─ Easter Egg
```
The root has nine stable pages. Hidden legacy cartridge and SSC firmware loaders
remain in the configuration string for native startup-file compatibility. They
are not additional top-level pages or everyday user setup steps.
## Choosing devices and disks
Built-in devices move sockets. Selecting a second Floppy, for example, moves the
existing controller and its mounted disks to the newly chosen socket. Assigning
Sound & Speech or Orchestra90 separately can split the corresponding portion out
of Audio expansions. Other instances are cleared deterministically, preserving
one instance of each real built-in controller. ROM files may occupy multiple
sockets simultaneously within the shared allocation limit.
Startup slot chooses the socket selected when the guest starts; it does not
rotate disk-controller types or change which disk image is mounted. The guest
can subsequently change its Multi-Pak selectors. Use Floppy Disks or CoCo SDC to
mount media for that controller. The rows are disabled when the corresponding
controller is absent. The OS9 mount names intentionally retain the upstream
/d0, /d1, /d3, /d4 conventions; they are not renumbered to imply new drive logic.
Changing a socket device restarts the CoCo. Mount media and save your MiSTer core
configuration after arranging the machine. On the next launch, remembered ROMs
are restored with the saved layout; no manual SSC chip-ROM loading is needed.
The installer preserves an existing Plus CFG rather than imposing a new layout.
## Sound and display
Assign an SSC-capable socket, select Sound & Speech on the expansion page and
check ready before running cartridge software. Extended palette and SSC share
register space, so this is an ownership selection. Audio expansions is a
compatibility convenience for SSC plus Orchestra90, not a third sound chip.
MiSTer supplies audio through its supported HDMI/analog configuration; a remote
video capture device may omit or mute HDMI audio even when core output works.
## Returning to MiSTer
Use MiSTer's OSD system/core-selection controls to choose another core without
a physical power switch. Save guest files first. Guest Reset/Cold Boot operate
on the CoCo environment; they are different from loading another RBF or turning
the whole MiSTer off.
+37
View File
@@ -0,0 +1,37 @@
# Two delivery forms, one core payload
The release design has two delivery targets:
1. **Existing MiSTer:** a checked FAT-volume overlay, copied directly or installed
over passwordless SSH. This is implemented by tools/release.py and
tools/install_mister.py.
2. **Dedicated Coco 3 Plus card:** a bootable image containing the standard
MiSTer system plus the same overlay, suitable for balenaEtcher. The image
builder and first-boot qualification are a separate delivery step; no bootable
Plus image is claimed by the core build or overlay packaging command.
MiSTer Linux and its boot files reside on the microSD card. It is not sufficient
to put a core RBF and games on a blank FAT32 card and rely on an onboard OS.
[Mr. Fusion](https://github.com/MiSTer-devel/mr-fusion) is the existing starter
system. Its compact image boots a small installer, expands/prepares the card,
installs MiSTer and reboots. Its documented image-writing tools include Etcher.
Using its existing release/system assets avoids building a new Linux distribution.
Its upstream full image builder currently uses a privileged Linux/Docker flow;
that is distinct from our native Windows FPGA/tool/ROM build.
For a dedicated release, pin the Mr. Fusion and MiSTer system versions and
checksums, preserve their licenses, then integrate the already verified Plus
overlay into the image's installation payload. Confirm exactly when the
installer consumes/deletes its staging partition before injecting files: copying
arbitrary assets beside Scripts is not a documented automatic full-root overlay
mechanism. Include only approved software-library content, no owner credentials,
SSH host keys or personal device configuration. Choose a dedicated startup
configuration deliberately while retaining a way back to MENU.
Qualification must include flashing a spare card, first-boot expansion on the
actual DE10-Nano, offline/online behavior, automatic SSC ROM availability when
legitimately supplied, readable/writable disks, saved settings and a cold power
cycle. Never replace an existing owner's primary card as an incidental test.
The same core/ROM/file manifest should identify both distribution forms so they
cannot drift into different products.
+132
View File
@@ -0,0 +1,132 @@
# Validation and acceptance scope
## Final named release, 2026-11-18
The final source embeds **Coco 3 Plus** as its display identity and retains
`coco3plus` as its native MGL profile. Original contribution copyright notices
are added without replacing upstream notices. A fresh native Quartus17.0.2
seed5 compile completes in **14:33**, **0 errors / 73 warnings**. It uses
**19,067 ALMs (45%)**, **495 RAM blocks (90%)** and produces a **3,946,736-byte** RBF:
```text
768ee9db2923bf7b7acf7f57473c6c56f92d14ffc6d6bd88719148f80c9a2d42
```
Minimum constrained slack: setup **+0.089 ns**, hold **+0.212 ns**, recovery
**+0.691 ns**, removal **+0.701 ns**, pulse width **+0.396 ns**. All 15 functional
jobs pass through the documented Windows entry point using the standalone
checkout's own verified/extracted simulator. The actual Main name-reader
fixture additionally confirms the spaced display name and unchanged canonical
profile override. All **368 fitted report scopes** pass, with remaining optional
pin contracts explicitly classified in validation/standalone.json. No timing
exceptions or physical delay assumptions were relaxed for the rename.
Release-tool review adds eight passing integrity tests: committed-only source
export excludes untracked notes and ROMs, public packages omit firmware, dirty
selected sources stop packaging, incomplete simulator setup stays unpublished,
and same-size binary corruption is detected. New HDL dependencies use a maintained
inventory; the build receipt reads the actual QSF seed. Resumed timing audits
require the original RBF, fitted netlist, input and Tcl-script identities. Older
unbound evidence is deliberately rejected; all 368 scopes were rerun with the
bound evidence format. These tooling corrections do not alter the fitted RTL.
This is a new bitstream, so previous extensive hardware observations below
belong to the earlier hash. Final deployment/startup observations are separately
recorded in validation/deployment.json. The shared logical implementation is
covered by the final-source regressions; no new human listening or cold-power
test is inferred merely from that relationship.
## First standalone reconstruction, 2026-11-18
The new repository was created from a complete upstream mirror, with no research
repository ancestry. The baseline is
`8b8cf72d1fb4de1d05345de8d5b92ec2d500fcd2`; original upstream refs are recorded in
validation/upstream-refs.json. The consolidated implementation is maintained on
main. Source-import hashes record the qualified implementation inputs and three
project-description comment rewrites; no private conversation/evidence archive
is required to build this project.
All public dependencies were freshly downloaded and hash-verified from the new
repository's scripts. Native Windows LWASM 4.25 assembled all four ToolShed ROMs
to the expected SHA-256 values. SSC original inputs were separately verified and
remain ignored. No VCC Plus checkout/build or private emulator binary was used
for this standalone build or these regressions.
The first standalone Quartus **17.0.2 Build 602** compile, seed 5, completed in
**14:38**, with **0 errors and 73 warnings**. Utilization is **19,098 ALMs (46%)**,
**495 RAM blocks (90%)** and 3,897,605 block-memory bits (69%). The RBF is
3,951,104 bytes, SHA-256:
```text
a4b6ef0b3641bbbc1b42de88502b677a1ec5e3809e2a17abf6f1e75c2a38451e
```
This first build is byte-identical to the previously qualified and hardware-tested
image. It still reported the retired COCO3-BH embedded identity, which the final
release changes to Coco 3 Plus. Its fit has minimum constrained setup **+0.069 ns**, hold **+0.252 ns**,
recovery **+0.692 ns**, removal **+0.742 ns**, pulse width **+0.396 ns** and summary
TNS zero. Generated build logs and exact source hashes remain under ignored build
storage; the sanitized reproducibility record is validation/standalone.json.
All **15 standalone functional jobs** pass: MPI allocation/config/router and actual
core bindings; original-ROM SSC system; registered interfaces; reset/buffer
domains; exhaustive keyboard phase; peripheral phase; SDRAM commands; delayed
CPU/video data; audio; pixel; I2C; original Main startup parser; original Main menu
parser; original/candidate video comparison. Negative controls include incorrect
buffer cadence, pixel duty/address corruption and old initialization behavior.
All seven native detailed timing audits pass **368 report scopes** at both slow
and fast corners. This includes 34 MPI reports, 144 live SSC path reports,
CPU/reset/NMI/UART/video scopes, and 48 substantive conditional external-I/O
reports. Explicitly empty synchronous-only recovery/removal subscopes are listed
as empty, not counted as an observed path with positive slack.
The first exported test run found missing dynamically named reset benches, a
canonical-name fixture mismatch, and a video-runner argument mismatch. These
were export-harness defects; corrected fixtures pass in a fresh output folder.
No RTL/timing exceptions were changed to satisfy the exported tests.
## Hardware evidence on these exact RBF bytes
Previous physical validation of the same image includes normal Disk BASIC startup,
saved non-default socket layout, Slot1/Slot4 ROM autoload, independent socket
banks/selectors, fresh configuration boot and Colour Lab grid/ramp/stripes/return.
Further autonomous checks include:
- 14 guided Sound Lab cases plus repeated/FF-operand cases: 20 transaction
records across seven validated saved reports. One deliberate active-speech
abort/reset returns to normal operation and completes the full greeting.
- Disk BASIC formatting of an authored scratch disk, writing and reading 256
exact numeric pairs across two granules; guest sums and host extraction agree.
- Supplied 512K RAM stress advancing pages for 135 seconds with no error display.
- Quadrapassel startup, keyboard movement, pause and quit.
- Mouse-as-right-joystick axes and button1 changes.
Human SSC audibility was confirmed during earlier integration checks. The later
autonomous report marks remain UNSURE/NOT_OBSERVED; no new listening score is
manufactured from screenshots or transaction completion. An earlier hardware
game check also confirmed USB joystick/game audio, with separate build attribution.
The initial standalone installer/path activation reached BASIC, `PRINT 1+1`
returned 2 and the OSD reported automatic Sound & Speech ready and Orchestra90
enabled. The saved CFG and stock RBF were preserved. Final renamed-image
activation is recorded separately in validation/deployment.json. Rebuilding identical bytes
does not itself prove a newly changed launcher/installer path works.
## Explicit remaining limits
The native external constraints use the controller's documented Alliance -7
SDRAM and bounded board-delay assumptions. The enclosed development module's
exact chip/speed suffix and PCB delays have not been independently measured.
This is conditional timing closure, not universal SDRAM-module or whole-board
electrical certification. Some HPS/muxed/asynchronous optional pins have separate
contracts outside these fabric STA budgets.
Cold power removal/reapplication remains a physical operator check. Longer memory
stress, every turbo/large-memory setting, all UART/serial electrical paths, every
SDC/VHD/OS9 and cassette-write format, all joystick types and exhaustive waveform
equivalence remain outside the enumerated acceptance scope. Firmware diagnostics
and human listening complement rather than replace timing/simulation evidence.
A dedicated bootable SD image requires separate first-boot/expansion/cold-start
qualification on a spare card; a verified core overlay is not that qualification.