Files
CoCo3_Plus_MiSTer/docs/VALIDATION.md
T

147 lines
8.4 KiB
Markdown

# Validation and acceptance scope
## Source-tree hygiene, 2026-11-18
Removed the inherited 162-byte Word owner/lock file `docs/~$Co3FPGA.docx`
from the current tree and ignore future Word lock files. Its history is preserved
in the original upstream commits (first present in the January 2022 check-ins;
updated May 2024). The actual CoCo3FPGA DOCX/PDF manuals are retained. This changes
no RTL, tool input, ROM or existing image; no FPGA rebuild or hardware test is
claimed for this documentation-only cleanup. Existing build/source receipts keep
their original pinned revisions.
## 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
```
Quartus summary 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** are classified: **288 contain
measured paths that pass**, and **80 are explicitly empty recovery/removal checks**.
The smallest enumerated detailed-path slack is **+0.065 ns**, distinct from the
summary setup minimum above. 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 classify **368 report scopes** at both slow
and fast corners: **288 measured scopes pass**, and **80 synchronous-only
recovery/removal scopes are explicitly empty**. 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.
## Earlier hardware evidence: RBF a4b6ef0b (not final RBF 768ee9db)
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.