Files
CoCo3_Plus_MiSTer/docs/BUILD_WINDOWS.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

6.2 KiB

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:

& C:\intelFPGA_lite\17.0\quartus\bin64\quartus_sh.exe --version

Obtain installers through the official Altera software download center. See also MiSTer's compilation guidance. 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

.\windows\Setup-Tools.ps1

This downloads native Windows x64 LWTOOLS 4.25, eight pinned ToolShed 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

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

.\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:

.\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:

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

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