Files
VCCPlusDiagnostics/examples/sound-lab/vectors/PROTOCOL.md
T

116 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.