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

+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.