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.
130 lines
6.2 KiB
Markdown
130 lines
6.2 KiB
Markdown
# 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.
|