Harden release packaging and recoverable installation after review
This commit is contained in:
1 parent
cb40fed3b9
commit
8088c1fbf6
14 files changed
+933
-101
No files matched your search
+54
-1
@@ -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
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
|
||||
Reference in new issue
Block a user