Publish the reproducible Sound Lab and FPGA Colour Lab sources
This commit is contained in:
commit
88254d7e24
27 files changed
+4574
No files matched your search
@@ -0,0 +1,157 @@
|
||||
# Sound Lab host reports
|
||||
|
||||
`python3 soundlab_reports.py` requires Python 3.10 or later and only the standard
|
||||
library. It reads existing disk images and report files; it does not run the
|
||||
emulator, touch a mounted disk, contact a service or modify source inputs.
|
||||
|
||||
## Extract and preserve reports
|
||||
|
||||
Quit or safely eject/save the writable diagnostic disk first, then copy it to a
|
||||
host working folder. Extract from that saved copy:
|
||||
|
||||
```sh
|
||||
python3 examples/sound-lab/host/soundlab_reports.py extract /path/to/SOUNDLAB.DSK \
|
||||
--output /path/to/run-exports
|
||||
```
|
||||
|
||||
The input must be a raw, single-sided, standard 35-track Disk BASIC disk image:
|
||||
35 tracks × 18 sectors × 256 bytes = 161,280 bytes. DMK, images with headers and
|
||||
other geometries are rejected rather than guessed. Selected filenames are
|
||||
`SND0000.TXT` through `SND9999.TXT`, case-insensitively. Reports must have the
|
||||
Disk BASIC ASCII flag `FF`; the guest writes directory type 3 (text). The tool
|
||||
preserves every selected file's exact bytes, normalizes its output filename to
|
||||
uppercase, and writes `extraction.json` with the original disk's SHA-256, each
|
||||
report's SHA-256/byte count and its granule chain.
|
||||
|
||||
Validation covers the directory, file type/ASCII flag, final-sector byte count,
|
||||
FAT values, fragmented chains, cycles, free granules in a file chain, duplicate
|
||||
names, unsafe names and crosslinks involving *any* active file. The directory
|
||||
track is excluded from granule addressing. Unclaimed FAT allocations are allowed
|
||||
because interrupted writes can leave them; the extractor does not repair them.
|
||||
It validates filesystem structure, not the authenticity of the disk's contents.
|
||||
|
||||
An existing output is never replaced implicitly. Prefer a fresh output folder
|
||||
for each run. `--overwrite` permits replacement of ordinary output files only;
|
||||
symlinks, inputs and hardlinks to inputs are still rejected. Keep the source
|
||||
`.DSK` and extracted `.TXT` as original evidence. The extractor never reformats,
|
||||
repairs or writes back to the disk.
|
||||
|
||||
## Convert and compare
|
||||
|
||||
```sh
|
||||
python3 examples/sound-lab/host/soundlab_reports.py convert \
|
||||
/path/to/run-exports/SND0001.TXT --output /path/to/readable-run \
|
||||
--manifest .build/sound-lab/SOUNDLAB-manifest.json
|
||||
|
||||
python3 examples/sound-lab/host/soundlab_reports.py compare \
|
||||
/path/to/vcc/SND0001.TXT /path/to/real-coco/SND0001.TXT \
|
||||
--output /path/to/comparison \
|
||||
--manifest .build/sound-lab/SOUNDLAB-manifest.json
|
||||
```
|
||||
|
||||
Conversion writes JSON, CSV and a self-contained readable HTML file. The JSON
|
||||
retains all recorded run metadata and per-case fields; CSV keeps raw timing/status
|
||||
fields as columns. The HTML escapes report text and includes no scripts or remote
|
||||
assets. No audio files or listening claims are manufactured.
|
||||
|
||||
The optional authoritative manifest has this supported structure (other fields
|
||||
such as artifact hashes may also be present):
|
||||
|
||||
```json
|
||||
{
|
||||
"build_id": "BUILD-IDENTITY",
|
||||
"vector_set_crc16": "1234",
|
||||
"vectors": [{"case_id": "TON01-A", "crc16": "7ABC"}]
|
||||
}
|
||||
```
|
||||
|
||||
The vector list may alternatively be an object such as
|
||||
`"vectors": {"TON01-A": "7ABC"}`. CRC values in the manifest may be four-digit
|
||||
hex strings, strings prefixed with `0x`, or JSON integers. Use ordinary four-digit
|
||||
hex in report records. Uppercase manifest keys `BUILD_ID` and
|
||||
`VECTOR_SET_CRC16` are accepted aliases. A manifest binds the guest's short build
|
||||
and vector IDs to the host build receipt; a CRC is not a cryptographic signature.
|
||||
The separate artifact hashes establish which binary/disk bytes were built.
|
||||
|
||||
Comparison requires the same nonempty `BUILD_ID`, `VECTOR_SET_CRC16` and matching
|
||||
per-case `VECTOR_CRC16`. With a manifest, both reports must match its declared
|
||||
identities too. Without one, the result explicitly states
|
||||
`identity_basis=REPORT_CLAIMS_ONLY`. Different/missing identities, missing cases,
|
||||
partial reports or failed integrity checks produce `NOT_COMPARABLE`, with the
|
||||
recorded evidence still shown. Comparable cases show `SAME` or `DIFFERENT` and
|
||||
list differing metrics, raw status, timings or notes. Matching these values does
|
||||
**not** establish matching audible output or equal analog timing precision.
|
||||
|
||||
`AUTO` and `HUMAN` are separate columns. `AUTO=OBSERVED` never becomes
|
||||
`HUMAN=HEARD`. Missing outcomes remain `UNKNOWN`; unknown timing resolution stays
|
||||
unknown. The tool checks report consistency and identities; it does not certify
|
||||
the author's automatic verdict or make hardware pass/fail assertions.
|
||||
|
||||
Exit status is 0 for successful valid conversion/comparison or extraction, 1 for
|
||||
an unreadable/unsupported input or refused output, and 2 when result files were
|
||||
written but evidence is partial, invalid or not comparable. Inspect the JSON/HTML
|
||||
issues instead of treating exit 2 as a completed run. Optional absent checksum or
|
||||
count fields are explicitly `NOT_PROVIDED`, never `VERIFIED`.
|
||||
|
||||
## SOUNDLAB-1 record contract
|
||||
|
||||
The first nonblank line is exactly `FORMAT=SOUNDLAB-1`. Subsequent ordinary lines
|
||||
contain space-separated `KEY=VALUE` tokens with uppercase keys and nonempty values.
|
||||
Values containing whitespace belong in escaped `NOTE` records. CRLF is preferred;
|
||||
LF is accepted. Bare CR, non-ASCII bytes and unescaped control characters are
|
||||
rejected. Empty/whitespace-only lines are ignored for record counts and checksums.
|
||||
Unknown metadata and per-case keys are retained for forward-compatible evidence.
|
||||
A different `FORMAT` requires a new parser version.
|
||||
|
||||
A header declares the run, target and build/vector identity. A case starts with
|
||||
`CASE=... VECTOR_CRC16=HHHH AUTO=... HUMAN=...`; subsequent lines carry its metrics.
|
||||
`ENDCASE` must match that case's identity. A per-case `REPEAT=0` field identifies
|
||||
the first attempt, `REPEAT=1` the next, and so on. Each `(CASE, REPEAT)` pair must
|
||||
be unique within a report. Omitted `REPEAT` defaults to 0 for early SOUNDLAB-1
|
||||
compatibility. Attempts are retained separately in JSON/CSV/HTML and compared by
|
||||
that pair, even if recorded in a different order. An interrupted case/run is preserved
|
||||
and marked incomplete. Case IDs and outcome enumerations compare
|
||||
case-insensitively; the original text/fields remain available.
|
||||
|
||||
Allowed automatic values: `PASS`, `FAIL`, `OBSERVED`, `TIMEOUT`, `NOT_RUN`,
|
||||
`NOT_APPLICABLE`. Allowed human values: `HEARD`, `WRONG`, `NO_SOUND`, `UNSURE`,
|
||||
`NOT_OBSERVED`, `SKIPPED`.
|
||||
|
||||
An optional note consists of two consecutive records inside a case:
|
||||
|
||||
```text
|
||||
NOTE_LENGTH=18
|
||||
NOTE=FIRST LINE\nSECOND!\n
|
||||
```
|
||||
|
||||
`NOTE_LENGTH` counts decoded ASCII **bytes**, not the serialized escape length.
|
||||
Escapes are `\\`, `\n`, `\r`, `\t` and `\xHH` (ASCII 00–7F). `NOTE=` consumes the
|
||||
rest of its line, including spaces. Length mismatch, unknown escapes, a dangling
|
||||
length or a note outside a case is reported as invalid/incomplete evidence.
|
||||
|
||||
A finished run ends with one footer, with no following nonblank records:
|
||||
|
||||
```text
|
||||
ENDRUN=0001 COMPLETE=YES RECORD_COUNT=8 CHECKSUM_CRC16=1234
|
||||
```
|
||||
|
||||
The run number must match `RUN`. `COMPLETE=NO` explicitly retains an interrupted
|
||||
run. Footer integrity fields are optional for interoperability; the diagnostic
|
||||
writer supplies both. `RECORD_COUNT` is the number of preceding nonblank lines,
|
||||
including `FORMAT` and every case, note and `ENDCASE` line, excluding the footer.
|
||||
`CHECKSUM_CRC16` is CRC-16/CCITT-FALSE: polynomial `1021`, initial `FFFF`, no
|
||||
reflection, no final XOR. It covers those same original nonblank lines joined
|
||||
with CRLF, **including a final CRLF**, and excludes the footer. Lowercase and
|
||||
uppercase hex are equivalent. Example footer values above are schematic.
|
||||
|
||||
## ROM-free checks
|
||||
|
||||
```sh
|
||||
python3 -m unittest discover -s examples/sound-lab/tests -p test_reports.py -v
|
||||
```
|
||||
|
||||
The authored fixtures cover fragmented disks across the reserved track, full
|
||||
sectors/granules, truncation, malformed FAT and loops/crosslinks, report end
|
||||
markers, notes, count/checksum validation, independent outcome comparisons,
|
||||
manifest identities, raw metric differences and output preservation. They use no
|
||||
private ROMs, real reports or actual hardware recordings.
|
||||
Reference in new issue
Block a user