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,115 @@
|
||||
# Sound Lab packet contract
|
||||
|
||||
The generator authors new diagnostic packets. It does not copy a manual's BASIC
|
||||
listings, include ROM bytes, call an emulator-private interface, or alter the SDK.
|
||||
Run it with the standard Python library:
|
||||
|
||||
```sh
|
||||
python3 examples/sound-lab/vectors/generate.py --output .build/sound-lab/generated
|
||||
python3 -m unittest discover -s examples/sound-lab/tests -p test_vectors.py -v
|
||||
```
|
||||
|
||||
`vectors.json` records exact command-port bytes, byte counts, SHA-256 and
|
||||
CRC-16/CCITT-FALSE for each stable case ID. `vector_set_crc16` covers those bytes
|
||||
concatenated in manifest order. Its checksum is an identity, not a claim that a
|
||||
cartridge produced the intended sound. The manifest SHA covers canonical sorted
|
||||
JSON before its own `manifest_sha256` property is appended.
|
||||
|
||||
`vectors.h` is generated into the requested output folder. Each `SoundVector`
|
||||
has `id`, `title`, `prompt`, `tx`, `length`, `crc16`, `wait_mask`, `hold_ticks`,
|
||||
and `group`. Group bits are 1 showcase, 2 short guided lab, 4 engineering sweep.
|
||||
The titles and prompts fit the guest's 32-column presentation with wrapping.
|
||||
The `wait_mask` conventions are current SDK/model observations: 40 speech idle,
|
||||
20 sound idle, 60 both. They must be logged as observations and never used to
|
||||
infer physical cartridge presence. `hold_ticks` adds a bounded observation time
|
||||
before the runner sends a safety stop. An NTSC60Hz tick assumption belongs in
|
||||
the report; a PAL machine must be identified separately.
|
||||
|
||||
Before each TX byte, including terminators, poll ready80 at FF7E with a bounded
|
||||
timeout. The runner owns reset, machine/sound routing preservation, timeout
|
||||
recovery, report I/O, manual sound checks and the safety stop after every case.
|
||||
The runner must record any timer/reset/control prelude and cleanup separately
|
||||
from these vector bytes so their receipt does not silently disagree with actual
|
||||
bus traffic. Use the same prelude, TX bytes and cleanup on all three platforms.
|
||||
Reset/control operations are not inferred from the text of a listening prompt.
|
||||
|
||||
## Source qualification
|
||||
|
||||
The primary publication is Tandy's1984 owner's manual. `sources.json` identifies
|
||||
the retrieved54-page2004 Tim Lindner OCR/typeset reproduction by URL, SHA-256 and
|
||||
byte count. This is a reproduction of the primary publication, **not a photographic
|
||||
scan**. The command-table, direct-register and event-grammar page pixels were
|
||||
rendered and inspected. Original-paper/photographic comparison remains pending;
|
||||
that limitation must remain visible in the build's qualification notes.
|
||||
|
||||
The Archive's old filename no longer downloads. Its currently downloadable
|
||||
`Speech-Sound Cartridge Manual (Tandy).pdf` is a newer57-page re-typeset edition.
|
||||
It is retained only as discovery evidence and is not silently substituted for
|
||||
the edition/page numbering cited here. No PDF is tracked or included on disk.
|
||||
|
||||
The primary source contains inconsistencies. Printed24 says register1–13 in
|
||||
introductory prose but its table, note and printed25 example use register0.
|
||||
Appendix B describes R8–R10 bit4 for envelope amplitude although the compact
|
||||
printed24 table only lists fixed amplitudes0–15. Printed19 contains contradictory
|
||||
parenthetical wording about noise replacement; the explicit Byte2 bit7 paragraph
|
||||
defines retain-previous-amplitude behavior. We preserve these qualifications
|
||||
rather than inventing undocumented commands.
|
||||
|
||||
## Source-qualified packet grammar
|
||||
|
||||
All numbers below are hexadecimal. Sources are printed pages in the54-page
|
||||
edition, with1-based PDF page equal to the printed page.
|
||||
|
||||
| Operation | Bytes | Primary source |
|
||||
| --- | --- | --- |
|
||||
| Immediate text | printable uppercase ASCII, space,0D | pp9–11; space is Sound Lab's explicit flush policy |
|
||||
| Stored text slot n | 90+n, text, space,0D; execute D0+n | Appendix A pp26–28 |
|
||||
| Allophone slot n | B0+n, codes00–3F, final pause00–04,FF; execute F0+n | pp13–14, Appendix A pp27–29 |
|
||||
| Sound slot n | 98+n, complete events,FF; execute D8+n | pp15–20, Appendix A pp26–29 |
|
||||
| Register-string slot n | B8+n, register/value pairs,FF; execute F8+n | Appendix A pp28–30 |
|
||||
| Direct AY register writes | AF, register,value pairs,FF | pp24–25, Appendix A p27 |
|
||||
| Timer base | 8F,value00–FF | Appendix A p26 |
|
||||
| Speech stop | C7 | Appendix A p28 |
|
||||
| Sound stop | CF | Appendix A p28 |
|
||||
| Stop both, retain buffers | 00 | Appendix A p30 |
|
||||
|
||||
Slots n range0–7. Text/allophone representations use the same eight speech
|
||||
slots. Sound events/register strings use the same eight sound slots. Consecutive
|
||||
multi-buffer operations exist but are deliberately outside this initial
|
||||
single-slot packet validator. Its conservative maximum64-byte body includes
|
||||
the terminator. It rejects overflow instead of relying on firmware truncation.
|
||||
|
||||
Tone event: channel00/20/40 OR amplitude00–0F (or envelope bit10), coarse00–0F,
|
||||
fine00–FF,duration00–FF. Noise event:80/A0/C0 OR amplitude, period00–1F with
|
||||
optional retain-amplitude bit80,duration. Envelope event:60 OR shape00–0F,
|
||||
coarse00–FF,fine00–FF,duration. The manual also permits bit7 set on the envelope
|
||||
operation; Sound Lab uses the simpler60 family.
|
||||
|
||||
An FF at a sound-event boundary ends the stream. FF consumed as a tone fine
|
||||
period, duration or envelope operand is data. In direct/register strings, FF is
|
||||
an end marker only where a register number is expected; a register's value may
|
||||
be FF when its field width permits it. It is not correct to split all packets
|
||||
at the first FF byte.
|
||||
|
||||
Event duration is the interval before the next event; it does **not** turn off
|
||||
the final note. Finite vectors include explicit amplitude-zero events. REG01,
|
||||
REG02 and MIX01 deliberately hold an audible output, then depend on the runner's
|
||||
bounded stop. TIM01 intentionally changes the timer base; the runner resets or
|
||||
restores a declared baseline between cases. Absolute milliseconds, ready-poll
|
||||
counts, intonation, analog waveform fidelity and comparative envelope shape are
|
||||
`MEASURE_BASELINE`, never an invented source pass.
|
||||
|
||||
## Existing SDK conventions kept separate
|
||||
|
||||
The source of the current SDK helpers is useful integration evidence, not a
|
||||
substitute for the publication. Its text62-character cap and appended space are
|
||||
conservative API rules. Its cold one-shot envelope prime/retrigger sequence is
|
||||
an implementation workaround: these vectors instead issue the documented
|
||||
envelope-enabled tone immediately followed by its envelope event. Allophone
|
||||
mnemonics are labels only; an observed or heard sound still needs a HUMAN result.
|
||||
|
||||
The generator's eight stored speech and eight stored sound cases exercise slot
|
||||
addressing independently. The64 allophone cases include five explicit silent
|
||||
pause cases. The16 envelope cases request each shape without asserting that
|
||||
the current emulator or future FPGA is already physically accurate. No audible
|
||||
or real-hardware validation is claimed by successful Python tests.
|
||||
Reference in new issue
Block a user