Harden release packaging and recoverable installation after review

This commit is contained in:
bholman committed 2026-11-18 16:26:25 -07:00
1 parent cb40fed3b9
commit 8088c1fbf6
14 files changed
+933 -101

No files matched your search

+54 -1
View File
@@ -6,6 +6,24 @@ Use 64-bit Windows, Git for Windows and Python **3.10 or newer**. Scripts use th
Python standard library. PowerShell wrappers accept `-Python <full-path>` when
`python` is not on PATH. All commands below run from the repository root.
Use a full Git checkout. An extracted source-review ZIP has no `.git` metadata
and deliberately omits inherited binary/manual artifacts still present in the
historical project inventory; it is not the supported build checkout. A release's
`SOURCE-CHECKOUT.txt` gives the exact immutable revision and clone commands:
```powershell
git clone https://vccplus-git.brianholman.com/VCCPlus/CoCo3_Plus_MiSTer.git coco3plus
cd coco3plus
# Replace RELEASE_SOURCE_REVISION with the full hash in SOURCE-CHECKOUT.txt.
git checkout --detach RELEASE_SOURCE_REVISION
git rev-parse HEAD
```
Do not pass `--depth`; the clone preserves the original upstream history. Access
to the repository is required. Build tools invoke Git to record the source
revision; merely installing the Git executable does not make an archive a Git
checkout. Keep the pinned checkout unchanged while building and qualifying it.
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,
@@ -71,6 +89,9 @@ 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.
It also records the SHA-256 of the maintained project inventory. Packaging
requires this identity, the exact current hashed-input set, and matching bytes
for every input. A subset receipt cannot qualify additional or omitted inputs.
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.
@@ -120,10 +141,42 @@ 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
untracked local files. Installed notices are also read from committed Git blobs,
so an untracked file in `LICENSES/` is excluded from both archive layers. The
source-review payload uses a maintained path/type allowlist in `tools/release.py`;
historical RBFs, PDFs and Office files remain in full Git history but are omitted
from that payload. `SOURCE-CHECKOUT.txt` records the pinned full-clone build route.
`-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.
Legacy fitted receipts without `project_inventory_sha256` are rejected rather
than silently upgraded. Preserve the old build directory, RBF and evidence. The
supported independent qualification route is a fresh `Build-FPGA.ps1 -Output
build/fpga-qualified` run from the pinned checkout, followed by its own functional,
detailed timing and hardware checks appropriate to release acceptance. A
prepare-only comparison establishes input equality; it does not create fit or
timing evidence. Do not add an inventory hash to an old receipt and present it as
newly qualified. Packaging-only changes need not alter RTL, but do not waive this
receipt requirement.
The real local-package guards can target a new qualified build and package
without moving or editing historical evidence. From the checkout in PowerShell:
```powershell
$env:COCO3PLUS_TEST_BUILD = 'build/fpga-audit-receipt'
$env:COCO3PLUS_TEST_RELEASE = 'dist/coco3plus-audit'
python -B tests/test_release_guards.py
```
Paths are resolved relative to the repository root unless absolute. Defaults
remain `build/fpga` and `dist/coco3plus` when the overrides are absent. Missing
actual local artifacts cause explicit skips; these are separate from portable
fixture tests in `tests/test_tooling_guards.py`. A selected complete package must
have the current source inventory, outer ZIP, exact committed source revision,
and committed Greg Miller notice; an existing historical package lacking those
properties is a failure rather than a substitute for checking the new package.
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.
+48 -12
View File
@@ -27,11 +27,30 @@ activity. Installation returns to MENU, so the current guest session is ended.
```
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.
local input and writes a local per-attempt receipt naming the planned stage,
backup, destinations and temporary files. It then checks remote access, stages
and verifies every payload, and returns to MENU. All supporting assets are
installed and checked before activation: the uniquely addressed RBF, ROMs,
configuration/path files and notices. Existing saved configuration is preserved.
The volume is synced before the launcher is changed.
The launcher is the last asset installed. Its staged bytes are copied to a
temporary sibling beside the destination, SHA-256 checked, and atomically renamed
to _Computer/Coco 3 Plus.mgl. The installer checks the final bytes, syncs again
and optionally loads the launcher. This avoids exposing a new menu entry before
its supporting files are installed. Filesystem rename is not a claim of
power-loss certification or a transaction covering the entire SD card.
Receipts are retained in ignored release storage as
`install-receipt-<attempt>.json`; `install-receipt.json` holds the latest attempt's
complete JSON record. An existing latest receipt is also preserved before a new
attempt. Each phase and completed file is recorded. On failure or keyboard
interruption, the receipt retains the active phase/file, error and planned
recovery paths. Stage and backup files are not automatically deleted; an
already-existing remote attempt directory is rejected rather than merged.
The installer 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.
@@ -82,6 +101,12 @@ artifact that omits all boot and SSC ROMs. Supply the required ROMs before manua
copy/launch. The SSH installer rejects this incomplete-ROM package and directs
you to make a complete local package from your own verified inputs.
The included `corresponding-source.zip` is a source-review payload, not a Git
checkout. It excludes historical RBFs, PDFs and Office files retained in the full
repository. Build scripts need Git metadata and the full project inventory.
Follow `SOURCE-CHECKOUT.txt` beside the archive to clone the repository and check
out the exact release revision before following `docs/BUILD_WINDOWS.md`.
## First launch and recovery
Choose Computer → Coco 3 Plus. It should reach Disk Extended Color BASIC.
@@ -96,10 +121,21 @@ 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.
For rollback, return to MENU and use the receipt's stage/backup paths. If
failure happened before activation_attempted, the old launcher is unchanged,
but some supporting files may already have been replaced: restore their backed-up
versions if needed before loading the previous core. If activation was attempted,
launcher_activated: null means a transport failure left its outcome uncertain;
inspect the installed launcher rather than assuming it was rolled back. A null
loaded value likewise means the load command was attempted but not confirmed.
When the old launcher needs restoration, restore _Computer/Coco 3 Plus.mgl from
the remote backup directory. Its previously addressed RBF remains in place.
Restore backed-up boot/SSC/path files when 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.
Run python tests/test_install_mister.py to exercise launcher-last activation and
deliberate pre-activation interruption on a disposable local mock target. These
tests do not access a MiSTer or establish physical power-loss behavior.
+48
View File
@@ -0,0 +1,48 @@
# Third-party provenance and release review
Component-specific notices and terms apply. Hosting in an upstream repository is
provenance evidence, not by itself a new redistribution permission grant.
## Greg Miller CPU
- Original project: https://github.com/cavnex/mc6809
- Pinned original license: commit
`17e94a6ef163be8b79a9b15b2e814847b6062f0f`, `documentation/LICENSE.md`.
- Retrieved primary document SHA-256: `11d10d396eb75ce78dd49eccc4f575379106f2c5291e863eb653842532694d0a`.
- Selected option: **Standard BSD license**, permitting source and binary
redistribution subject to the stated conditions. The binary-only alternative
is not the selected option.
- Complete selected terms: [Greg-Miller-BSD-3-Clause.txt](../LICENSES/Greg-Miller-BSD-3-Clause.txt).
- Inherited derivative: `rtl/mc6809glb/mc6809glb.v`; original header retained.
- Independent review reports 99.4% normalized noncomment-token agreement with
the original mc6809i.v. This is an ancestry/provenance check, not a new claim of
ownership over original or later work.
## Additional inherited material under review
Before public source or binary release, complete the component review for:
- Generated Intel/Altera IP and device primitives: retain original vendor notices,
identify applicable free-source IP/programming-output terms and target-device
restrictions. The installed Quartus Prime 17.0 agreement's section 2.5 offers
source-IP redistribution terms for the defined free-source component category,
limited to programming Altera devices. Verify each generated family/version
against that category and preserve its notices; do not substitute the Plus
contribution license for those terms.
- `rtl/rom/coco3_char_rom.vhd`: 4,096 initialized character-font bytes are embedded
in HDL and wired into the fitted design. The romgen generator attribution does
not establish the font's separate provenance or distribution terms.
- Inherited reference PDFs and historical RBFs retained in original Git history:
review their distribution basis independently of source-code licenses. In
particular, `releases/Tandy CoCo3 Overview.pdf` is a community MiSTer reference
sheet added by Alan Steremberg in commit a8014eae0b9ee90928389d9ecb2a9a7962edf761,
not an identified original Tandy publication. Its artwork credits/terms are not
specified in the sheet.
Excluding a file from a downloadable source ZIP does not remove historical Git
objects or resolve their publication status.
- GPL-covered framework modules: retain notices, applicable GPL texts and build
materials/corresponding source obligations for combined distributions.
This list identifies release-review work. It does not revoke or replace original
component terms, establish a blanket prohibition, or claim that review is complete.
External boot and SSC ROMs remain separately supplied and ignored by Git.
+9 -5
View File
@@ -12,12 +12,15 @@ seed5 compile completes in **14:33**, **0 errors / 73 warnings**. It uses
768ee9db2923bf7b7acf7f57473c6c56f92d14ffc6d6bd88719148f80c9a2d42
```
Minimum constrained slack: setup **+0.089 ns**, hold **+0.212 ns**, recovery
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** pass, with remaining optional
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.
@@ -75,8 +78,9 @@ CPU/video data; audio; pixel; I2C; original Main startup parser; original Main m
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,
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.
@@ -86,7 +90,7 @@ 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
## 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