Publish the reproducible Sound Lab and FPGA Colour Lab sources

This commit is contained in:
bholman committed 2026-11-18 12:28:31 -07:00
commit 88254d7e24
27 files changed
+4574

No files matched your search

+4
View File
@@ -0,0 +1,4 @@
.build/
__pycache__/
*.pyc
.DS_Store
+674
View File
@@ -0,0 +1,674 @@
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<http://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<http://www.gnu.org/philosophy/why-not-lgpl.html>.
+72
View File
@@ -0,0 +1,72 @@
# VCC Plus Diagnostics
Standalone diagnostic disks for the Tandy Color Computer, VCC Plus, and
compatible FPGA implementations. Designed by Brian Holman · Sponsored by
Dezota LLC.
| Diagnostic | Tagged release | Get started |
| --- | --- | --- |
| Sound Lab | [SL1-44B5F46F](https://vccplus-git.brianholman.com/VCCPlus/VCCPlusDiagnostics/releases/tag/sound-lab-sl1-44b5f46f) | Use Disk BASIC and a Speech/Sound Cartridge. Boot a writable copy in drive 0 with `DOS`. |
| FPGA Colour Lab | [CL1](https://vccplus-git.brianholman.com/VCCPlus/VCCPlusDiagnostics/releases/tag/fpga-colour-lab-cl1) | Use Disk BASIC and enable compatible FPGA 256-color support. Leave the Speech/Sound Cartridge out. Run `RUN"COLORLAB"` from drive 0. |
Use a fresh machine session and keep a pristine disk master. The release pages
link to the exact disk, checksum and source package hosted in the VCC Plus
download area. The [compatibility paper](https://vccplus.brianholman.com/publications/ssc-fpga256/)
identifies the results obtained with these disk revisions.
## Build from a tag
Check out the release tag for the diagnostic you want to reproduce.
### Sound Lab
Use Python 3.10 or later and [VCC Plus 3.7.1 build 67's installed Mac toolchain](https://vccplus.brianholman.com/dl/software/VCCPlus/3.7.1-67/VCC-Plus-for-Mac-3.7.1-67-Universal.dmg),
which supplies CMOC 0.1.101, LWTools 4.25, the guest SSC and Disk BASIC
libraries, and the disk writer and boot-loader installer. The macOS command
below assumes the application is installed in Applications.
```sh
export PYTHONDONTWRITEBYTECODE=1
python3 examples/sound-lab/check.py \
--toolchain '/Applications/VCC Plus.app/Contents/Resources/Toolchain' \
--output .build/sound-lab-sl1
```
This runs the host checks, builds the disk, and records the input and output
hashes. The published source package contains the build inputs for the guest
libraries and the source or build recipes for the toolchain components used by
this release. See [Sound Lab operation and reporting](examples/sound-lab/README.md).
The optional headless VCC test compiles the retained runner against a local
VCC Plus checkout and built core library. On macOS set
`CPATH` to `<VCCPlus checkout>/tests/toolchain/ssc`, then add `--core` and
`--roms` with the paths to the core library and your local ROM directory.
The test boots a disposable copy and measures digital behavior and audio
activity. Listening assessments are recorded separately.
### FPGA Colour Lab
Use Python 3 and LWASM 4.25. The builder accepts an executable path on Mac
or Windows:
```sh
python3 examples/fpga256/build.py --lwasm /path/to/lwasm --output .build/colour-lab-cl1
```
On Windows use `py -3` and the path to `lwasm.exe`. See the
[Colour Lab controls](examples/fpga256/README.md) and the
[Windows FPGA handoff](docs/windows-handoff.md).
## Ownership and attribution
Maintain standalone diagnostic sources here. App and FPGA tests consume a
specific tagged release and verify the disk hash before making test copies.
The examples at the initial tags preserve the source inputs used to build
the published disks.
The original diagnostic source is GPL-3.0-or-later. See [COPYING](COPYING).
The Sound Lab bootstrap retains Pierre Sarrazin's public-domain notice and
credits Roger Schrag. The corresponding Sound Lab sources carry their
component notices. FPGA Colour Lab exercises the CoCo3FPGA extension by
Gary Becker and the MiSTer adaptation by Stan Hodge, Gary Becker and Alan
Steremberg. ROMs are supplied locally by the user for emulator tests.
+30
View File
@@ -0,0 +1,30 @@
# Windows and FPGA diagnostic handoff
Use this repository as the only maintained home for Sound Lab and FPGA
Colour Lab. Keep the FPGA harness and captures in the research repository.
Pin the diagnostic release in each test receipt.
| Diagnostic and release | Verified master SHA-256 |
| --- | --- |
| [Sound Lab SL1-44B5F46F](https://vccplus-git.brianholman.com/VCCPlus/VCCPlusDiagnostics/releases/tag/sound-lab-sl1-44b5f46f) | `56030b65202a2cc6fc2c9933327a766aa704febb27d9cca7bfcb42c2af6de6b6` |
| [FPGA Colour Lab CL1](https://vccplus-git.brianholman.com/VCCPlus/VCCPlusDiagnostics/releases/tag/fpga-colour-lab-cl1) | `d0ad804254c03f92de9fc8745fe068fdbd1a8d90bb069bd41ddf5a8541861c36` |
Download the disk from its release page. In PowerShell, use
`Get-FileHash -Algorithm SHA256 .\SOUNDLAB.DSK` or
`Get-FileHash -Algorithm SHA256 .\COLORLAB.DSK`. Compare it with the expected
master hash, then create a writable copy for each test. Retain Sound Lab
reports from the writable copy separately. Its modified disk hash is a
result of the session.
For a local Colour Lab rebuild, check out `fpga-colour-lab-cl1`, then run
`py -3 examples/fpga256/build.py --lwasm C:\path\to\lwasm.exe --output .build/colour-lab-cl1`
with LWASM 4.25. The exact Sound Lab build recipe uses VCC Plus's pinned
Mac toolchain. The verified raw disk is the Windows test input.
If the current test run uses local diagnostic edits or other disk bytes, retain
the original run and its identities. Before switching inputs on the next run,
compare those sources against the tags and report any differences. Include
application and FPGA branch tips, any commits absent from their pushed refs,
uncommitted source changes, generated disk hashes, and which inputs were used
for the run. Coordinate forward changes in this repository after the running
FPGA qualification completes.
+54
View File
@@ -0,0 +1,54 @@
# FPGA Colour Lab
Assembly-only, user-facing diagnostic for the optional CoCo3FPGA/MiSTer
256-color extension and VCC Plus's matching core option. It is **not a standard
CoCo graphics mode**. Use a fresh disposable BASIC machine; the diagnostic uses
physical RAM4000..B7FF as its framebuffer. Eject SSC and enable the extension.
No private ROM bytes are included in the source or disk.
## Build
Python3.9+ and LWASM4.25 are sufficient, on Windows or Mac/Linux:
```sh
python3 examples/fpga256/build.py --lwasm /absolute/path/to/lwasm --output .build/colourlab-run1
```
On Windows, supply `lwasm.exe` and the installed Python executable. The builder
requires a fresh output folder and preserves prior disks. VCC Plus on Mac
bundles LWASM in its compiler stack; no C/CMOC build is needed here.
The tracked `generated.inc` also lets the native assembly workspace assemble
`colorlab.asm` directly. The Python builder regenerates that include and creates
the complete test disk; the include is authored test data, not a private ROM.
Outputs: COLORLAB.DSK (35-track DECB), COLORLAB.BIN, ASCII COLORLAB.BAS, listing,
generated banner/palette input and a source/artifact SHA256 manifest. Keep the
master and manifest together; copy the disk for interactive tests.
## Play and inspect
In the Mac development build, enable **FPGA 256-color support** in Machine
Settings and apply the change. Mount a writable copy in FD0 in Disk BASIC.
Type `RUN"COLORLAB"`, read the instructions, then
press any key. The launch assumes ordinary32-column BASIC and returns to that
mode; it does not attempt to read back write-only GIME registers.
- **Grid:** 16 columns ×16 rows,256 distinct colors. Small cells are ordered
left-to-right, then top-to-bottom. Look for missing/duplicated cells or colors.
- **Space:** cycle grid, byte ramp and one-pixel alternating stripes. Look for
stable edges and consistent pixel ordering/row alignment.
- **A:** toggle palette animation. Colors move without redrawing the picture;
the black/white header entries are retained for readable controls.
- **Q:** restore the saved MMU mapping, standard BASIC video/ROM setup and caller
stack, then return. The keyboard is scanned directly and debounced, avoiding
patched BASIC POLCAT hooks while in the temporary graphics mapping.
Take a gallery photograph/screenshot, note platform/core/version and which
controls worked, then report any missing colors, seams or unexpected resets.
The disk does not claim to measure analog calibration. It does not yet save a
result file; automatic native tests record exact pixel/control checks separately.
Guest validation covers actual assembly on both 6809 and 6309 engines and a real
Disk BASIC RUN/LOADM/EXEC path. This is distinct from native Mac UI or physical
MiSTer acceptance. See the [Mac validation record](../../docs/development/FPGA256_MAC_VALIDATION.md)
for the separate host checks.
+79
View File
@@ -0,0 +1,79 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Build the assembly-only FPGA Colour Lab disk with native LWASM/Python."""
import argparse
import hashlib
import itertools
import json
from pathlib import Path
import shutil
import subprocess
PROJECT = Path(__file__).resolve().parent
FONT = dict(zip('ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 ', [
'25755','65656','34443','65556','74647','74644','34553','55755','72227',
'11152','55655','44447','57755','57775','25552','65644','25573','65655',
'34216','72222','55557','55552','55575','55255','55222','71247',
'75557','26227','61247','61216','55711','74616','34652','71111','25652','25716','00000']))
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--lwasm', type=Path, required=True)
parser.add_argument('--output', type=Path, required=True)
a = parser.parse_args()
output = a.output.resolve()
if output.exists(): parser.error('Use a fresh output folder; preserve prior disks.')
output.mkdir(parents=True)
version = subprocess.check_output([str(a.lwasm.resolve()), '--version'], text=True).strip()
image = bytearray(160*32)
for text, y in [('FPGA COLOUR LAB 256',2),('SPACE NEXT A AUTO Q QUIT',12),('1 GRID 2 RAMP 3 STRIPES',22)]:
left = (160 - len(text)*4)//2
for n,c in enumerate(text):
for row, bits in enumerate(FONT[c]):
for bit in range(3):
if int(bits)&(4>>bit): image[(y+row)*160+left+n*4+bit]=255
runs=[]
for value, group in itertools.groupby(image):
count=len(list(group))
while count:
part=min(count,255); runs.extend([part,value]);count-=part
runs.append(0)
words=[]
for i in range(256):
r,g,b=i>>5,(i>>2)&7,i&3
value=((r>>2)<<11)|(((r>>1)&1)<<8)|((r&1)<<5)|((g>>2)<<10)|(((g>>1)&1)<<7)|((g&1)<<4)|((b>>1)<<9)|((b&1)<<6)
words.extend([value>>6,value&63])
with (output/'generated.inc').open('w') as f:
for label,data in [('colours',words),('banner',runs)]:
f.write(label+'\n')
for start in range(0,len(data),16):f.write(' fcb '+','.join('$%02x'%v for v in data[start:start+16])+'\n')
shutil.copy2(PROJECT/'colorlab.asm',output/'colorlab.asm')
subprocess.run([str(a.lwasm.resolve()),'--format=decb','--output=COLORLAB.BIN','--list=COLORLAB.lst','colorlab.asm'],cwd=output,check=True)
binary=(output/'COLORLAB.BIN').read_bytes()
assert binary[0]==0 and int.from_bytes(binary[3:5],'big')==0x2000
assert 0x2000+int.from_bytes(binary[1:3],'big')<0x4000,'Code must stay below remapped framebuffer'
basic=b'10 PCLEAR1:CLEAR200,&H1FFF:CLS\r20 PRINT"FPGA COLOUR LAB - EXTENSION ONLY"\r30 PRINT"ENABLE 256 COLOURS; EJECT SSC."\r40 PRINT"GRID: 16 BY 16 DISTINCT COLOURS"\r50 PRINT"SPACE: NEXT PATTERN A: ANIMATE"\r60 PRINT"Q: RETURN. STANDARD COCO UNSUPPORTED"\r70 PRINT"PRESS ANY KEY TO START"\r80 IF INKEY$="" THEN80\r90 LOADM"COLORLAB":EXEC\r100 PRINT"RETURNED FROM COLOUR LAB"\r'
(output/'COLORLAB.BAS').write_bytes(basic)
disk=bytearray(b'\xff'*(35*18*256)); fat=(17*18+1)*256; directory=(17*18+2)*256; nextgranule=0
for index,(name,data,kind,ascii_flag) in enumerate([('COLORLAB.BAS',basic,0,255),('COLORLAB.BIN',binary,2,0)]):
first=nextgranule; count=(len(data)+2303)//2304
for n in range(count):
g=nextgranule; nextgranule+=1; chunk=data[n*2304:(n+1)*2304]
offset=((g//2+(g>=34))*18+(g%2)*9)*256
disk[offset:offset+len(chunk)]=chunk
disk[fat+g]=(g+1) if n+1<count else 0xc0+(len(chunk)+255)//256
base,ext=name.split('.'); entry=bytearray(32)
entry[:11]=(base.ljust(8)+ext.ljust(3)).encode();entry[11:14]=bytes([kind,ascii_flag,first])
entry[14:16]=(len(data)%256 or 256).to_bytes(2,'big');disk[directory+index*32:directory+(index+1)*32]=entry
(output/'COLORLAB.DSK').write_bytes(disk)
digest=lambda p:hashlib.sha256(p.read_bytes()).hexdigest()
manifest={'assembler':version,'cpu':'MC6809','requires':'FPGA 256-color extension; SSC absent',
'hardware_tested':False,'org':8192,'framebuffer':'physical 4000..B7FF; 160x192',
'source_sha256':{n:digest(PROJECT/n) for n in ['colorlab.asm','build.py']},
'artifacts':{n:{'bytes':(output/n).stat().st_size,'sha256':digest(output/n)} for n in ['COLORLAB.BIN','COLORLAB.BAS','COLORLAB.DSK','generated.inc']}}
(output/'manifest.json').write_text(json.dumps(manifest,indent=2)+'\n')
print('Built assembly-only Colour Lab:',output/'COLORLAB.DSK')
if __name__=='__main__':main()
+208
View File
@@ -0,0 +1,208 @@
* SPDX-License-Identifier: GPL-3.0-or-later
* Original MC6809 diagnostic; LWASM DECB output. No CMOC or private ROM bytes.
org $2000
start pshs cc,d,dp,x,y,u
sts oldstack
orcc #$50
lds #$0dff
* GIME video/INIT registers are write-only on a standard CoCo. Start this
* diagnostic from ordinary 32-column BASIC; return to that documented mode.
ldx #$ffa2
ldu #oldmmu
ldb #4
savem lda ,x+
sta ,u+
decb
bne savem
lda #2
ldx #$ffa2
mapram sta ,x+
inca
cmpa #6
bne mapram
lda #$4c * Native graphics, MMU, internal 32 KiB ROM
sta $ff90
clr $ff9a
clr $ff9c
clr $ff9f
lda #8
sta $ff9d
clr $ff9e
lda #$80
sta $ff98
lda #$1f * HRES7, CRES3 = 160 x 192, one byte/pixel
sta $ff99
clr phase
clr animate
clr page
clr lastkey
jsr palette
jsr draw
keys jsr readkey * Direct matrix scan; no BASIC ROM hook dependency
tsta
beq release
cmpa lastkey
beq idle
sta lastkey
cmpa #'Q
lbeq quit
cmpa #'q
lbeq quit
cmpa #'A
beq toggle
cmpa #'a
beq toggle
cmpa #32
beq next
idle tst animate
beq keys
ldx #2000
delay leax -1,x
bne delay
inc phase
jsr palette
bra keys
release clr lastkey
bra idle
toggle com animate
bra keys
next inc page
lda page
cmpa #3
blo redraw
clr page
redraw jsr draw
bra keys
readkey lda #$fd * Column 1: A is row0, Q is row2
sta $ff02
lda $ff00
bita #4
bne checka
lda #'Q
rts
checka bita #1
bne checks
lda #'A
rts
checks lda #$7f * Column 7, row3: SPACE
sta $ff02
lda $ff00
bita #8
bne nokey
lda #32
rts
nokey clra
rts
palette ldu #colours
ldy #256
ldb phase
pal lda ,u+
sta $ffb0 * Upper and lower six bits
lda ,u+
ora #$80 * Preserve upper six bits, replace lower
sta $ffb0
tst phase
beq commit
tstb
beq skippal
cmpb #255
beq skippal
commit
stb $ff7e * Index, not RGB data
skippal
incb
leay -1,y
bne pal
rts
draw ldx #$4000
ldu #banner
rle ldb ,u+
beq body
lda ,u+
run sta ,x+
decb
bne run
bra rle
body lda page
beq gallery
cmpa #1
beq ramp
ldy #160
stripe clra
ldb #160
strpx eora #$ff
sta ,x+
decb
bne strpx
leay -1,y
bne stripe
rts
ramp ldy #160
clra
ramprow ldb #160
ramppx sta ,x+
inca
decb
bne ramppx
leay -1,y
bne ramprow
rts
gallery clr rowbase
lda #16
sta rows
cellrow lda #10
sta lines
gridrow lda rowbase
ldb #16
cell ldu #10
cellpx sta ,x+
leau -1,u
cmpu #0 * LEAU does not update Z on a 6809
bne cellpx
inca
decb
bne cell
dec lines
bne gridrow
lda rowbase
adda #16
sta rowbase
dec rows
bne cellrow
rts
quit ldx #$ffa2
ldu #oldmmu
ldb #4
restm lda ,u+
sta ,x+
decb
bne restm
lda #$cc * Standard BASIC text, internal 32 KiB ROM
sta $ff90
ldx #$ff98
ldu #oldvideo
ldb #8
restv lda ,u+
sta ,x+
decb
bne restv
lds oldstack
lda #$ff
sta $ff02
puls cc,d,dp,x,y,u,pc
oldstack rmb 2
oldvideo fcb 0,0,0,0,$0f,$e0,0,0
oldmmu rmb 4
phase rmb 1
animate rmb 1
page rmb 1
rowbase rmb 1
rows rmb 1
lines rmb 1
lastkey rmb 1
include "generated.inc"
end start
+122
View File
@@ -0,0 +1,122 @@
colours
fcb $00,$00,$01,$00,$08,$00,$09,$00,$00,$10,$01,$10,$08,$10,$09,$10
fcb $02,$00,$03,$00,$0a,$00,$0b,$00,$02,$10,$03,$10,$0a,$10,$0b,$10
fcb $10,$00,$11,$00,$18,$00,$19,$00,$10,$10,$11,$10,$18,$10,$19,$10
fcb $12,$00,$13,$00,$1a,$00,$1b,$00,$12,$10,$13,$10,$1a,$10,$1b,$10
fcb $00,$20,$01,$20,$08,$20,$09,$20,$00,$30,$01,$30,$08,$30,$09,$30
fcb $02,$20,$03,$20,$0a,$20,$0b,$20,$02,$30,$03,$30,$0a,$30,$0b,$30
fcb $10,$20,$11,$20,$18,$20,$19,$20,$10,$30,$11,$30,$18,$30,$19,$30
fcb $12,$20,$13,$20,$1a,$20,$1b,$20,$12,$30,$13,$30,$1a,$30,$1b,$30
fcb $04,$00,$05,$00,$0c,$00,$0d,$00,$04,$10,$05,$10,$0c,$10,$0d,$10
fcb $06,$00,$07,$00,$0e,$00,$0f,$00,$06,$10,$07,$10,$0e,$10,$0f,$10
fcb $14,$00,$15,$00,$1c,$00,$1d,$00,$14,$10,$15,$10,$1c,$10,$1d,$10
fcb $16,$00,$17,$00,$1e,$00,$1f,$00,$16,$10,$17,$10,$1e,$10,$1f,$10
fcb $04,$20,$05,$20,$0c,$20,$0d,$20,$04,$30,$05,$30,$0c,$30,$0d,$30
fcb $06,$20,$07,$20,$0e,$20,$0f,$20,$06,$30,$07,$30,$0e,$30,$0f,$30
fcb $14,$20,$15,$20,$1c,$20,$1d,$20,$14,$30,$15,$30,$1c,$30,$1d,$30
fcb $16,$20,$17,$20,$1e,$20,$1f,$20,$16,$30,$17,$30,$1e,$30,$1f,$30
fcb $20,$00,$21,$00,$28,$00,$29,$00,$20,$10,$21,$10,$28,$10,$29,$10
fcb $22,$00,$23,$00,$2a,$00,$2b,$00,$22,$10,$23,$10,$2a,$10,$2b,$10
fcb $30,$00,$31,$00,$38,$00,$39,$00,$30,$10,$31,$10,$38,$10,$39,$10
fcb $32,$00,$33,$00,$3a,$00,$3b,$00,$32,$10,$33,$10,$3a,$10,$3b,$10
fcb $20,$20,$21,$20,$28,$20,$29,$20,$20,$30,$21,$30,$28,$30,$29,$30
fcb $22,$20,$23,$20,$2a,$20,$2b,$20,$22,$30,$23,$30,$2a,$30,$2b,$30
fcb $30,$20,$31,$20,$38,$20,$39,$20,$30,$30,$31,$30,$38,$30,$39,$30
fcb $32,$20,$33,$20,$3a,$20,$3b,$20,$32,$30,$33,$30,$3a,$30,$3b,$30
fcb $24,$00,$25,$00,$2c,$00,$2d,$00,$24,$10,$25,$10,$2c,$10,$2d,$10
fcb $26,$00,$27,$00,$2e,$00,$2f,$00,$26,$10,$27,$10,$2e,$10,$2f,$10
fcb $34,$00,$35,$00,$3c,$00,$3d,$00,$34,$10,$35,$10,$3c,$10,$3d,$10
fcb $36,$00,$37,$00,$3e,$00,$3f,$00,$36,$10,$37,$10,$3e,$10,$3f,$10
fcb $24,$20,$25,$20,$2c,$20,$2d,$20,$24,$30,$25,$30,$2c,$30,$2d,$30
fcb $26,$20,$27,$20,$2e,$20,$2f,$20,$26,$30,$27,$30,$2e,$30,$2f,$30
fcb $34,$20,$35,$20,$3c,$20,$3d,$20,$34,$30,$35,$30,$3c,$30,$3d,$30
fcb $36,$20,$37,$20,$3e,$20,$3f,$20,$36,$30,$37,$30,$3e,$30,$3f,$30
banner
fcb $ff,$00,$6b,$00,$03,$ff,$01,$00,$02,$ff,$03,$00,$02,$ff,$02,$00
fcb $01,$ff,$07,$00,$02,$ff,$02,$00,$01,$ff,$02,$00,$01,$ff,$04,$00
fcb $01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$02,$ff,$06,$00
fcb $01,$ff,$04,$00,$01,$ff,$02,$00,$02,$ff,$06,$00,$02,$ff,$02,$00
fcb $03,$ff,$02,$00,$02,$ff,$55,$00,$01,$ff,$03,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$03,$00,$01,$ff,$01,$00,$01,$ff,$05,$00
fcb $01,$ff,$03,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$03,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$05,$00,$01,$ff,$03,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$07,$00,$01,$ff,$01,$00
fcb $01,$ff,$03,$00,$01,$ff,$57,$00,$02,$ff,$02,$00,$02,$ff,$02,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$03,$ff,$05,$00,$01,$ff,$03,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$03,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$02,$ff,$06,$00
fcb $01,$ff,$03,$00,$03,$ff,$01,$00,$02,$ff,$07,$00,$01,$ff,$02,$00
fcb $02,$ff,$02,$00,$02,$ff,$56,$00,$01,$ff,$03,$00,$01,$ff,$03,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$05,$00
fcb $01,$ff,$03,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$03,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$05,$00,$01,$ff,$03,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$05,$00,$01,$ff,$05,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$55,$00,$01,$ff,$03,$00
fcb $01,$ff,$04,$00,$02,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$06,$00
fcb $02,$ff,$02,$00,$01,$ff,$02,$00,$03,$ff,$02,$00,$01,$ff,$02,$00
fcb $03,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$05,$00,$03,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$02,$ff,$06,$00,$03,$ff,$01,$00
fcb $02,$ff,$03,$00,$01,$ff,$ff,$00,$ff,$00,$ff,$00,$6c,$00,$02,$ff
fcb $01,$00,$02,$ff,$03,$00,$01,$ff,$03,$00,$02,$ff,$01,$00,$03,$ff
fcb $05,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$03,$ff,$01,$00,$01,$ff
fcb $01,$00,$01,$ff,$01,$00,$03,$ff,$0a,$00,$01,$ff,$07,$00,$01,$ff
fcb $02,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$03,$ff,$02,$00,$01,$ff
fcb $0b,$00,$01,$ff,$07,$00,$01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff
fcb $01,$00,$03,$ff,$01,$00,$03,$ff,$39,$00,$01,$ff,$03,$00,$01,$ff
fcb $01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $03,$00,$01,$ff,$07,$00,$03,$ff,$01,$00,$01,$ff,$03,$00,$01,$ff
fcb $01,$00,$01,$ff,$02,$00,$01,$ff,$0a,$00,$01,$ff,$01,$00,$01,$ff
fcb $05,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $02,$00,$01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff,$09,$00,$01,$ff
fcb $01,$00,$01,$ff,$05,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $01,$00,$01,$ff,$02,$00,$01,$ff,$03,$00,$01,$ff,$3b,$00,$01,$ff
fcb $02,$00,$02,$ff,$02,$00,$03,$ff,$01,$00,$01,$ff,$03,$00,$02,$ff
fcb $06,$00,$03,$ff,$01,$00,$02,$ff,$03,$00,$01,$ff,$03,$00,$01,$ff
fcb $0a,$00,$03,$ff,$05,$00,$03,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $02,$00,$01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff,$09,$00,$01,$ff
fcb $01,$00,$01,$ff,$05,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $01,$00,$01,$ff,$02,$00,$01,$ff,$03,$00,$01,$ff,$3c,$00,$01,$ff
fcb $01,$00,$01,$ff,$03,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $03,$00,$01,$ff,$07,$00,$03,$ff,$01,$00,$01,$ff,$03,$00,$01,$ff
fcb $01,$00,$01,$ff,$02,$00,$01,$ff,$0a,$00,$01,$ff,$01,$00,$01,$ff
fcb $05,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $02,$00,$01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff,$09,$00,$03,$ff
fcb $05,$00,$03,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$02,$00,$01,$ff
fcb $03,$00,$01,$ff,$3a,$00,$02,$ff,$02,$00,$01,$ff,$03,$00,$01,$ff
fcb $01,$00,$01,$ff,$02,$00,$02,$ff,$01,$00,$03,$ff,$05,$00,$01,$ff
fcb $01,$00,$01,$ff,$01,$00,$03,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff
fcb $02,$00,$01,$ff,$0a,$00,$01,$ff,$01,$00,$01,$ff,$05,$00,$01,$ff
fcb $01,$00,$01,$ff,$01,$00,$03,$ff,$02,$00,$01,$ff,$03,$00,$01,$ff
fcb $0b,$00,$02,$ff,$06,$00,$02,$ff,$01,$00,$03,$ff,$01,$00,$03,$ff
fcb $02,$00,$01,$ff,$ff,$00,$ff,$00,$ff,$00,$60,$00,$01,$ff,$07,$00
fcb $02,$ff,$01,$00,$02,$ff,$02,$00,$03,$ff,$01,$00,$02,$ff,$0a,$00
fcb $02,$ff,$06,$00,$02,$ff,$03,$00,$01,$ff,$02,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$02,$ff,$0a,$00,$02,$ff,$07,$00,$02,$ff,$01,$00
fcb $03,$ff,$01,$00,$02,$ff,$02,$00,$03,$ff,$01,$00,$02,$ff,$02,$00
fcb $03,$ff,$02,$00,$02,$ff,$3d,$00,$02,$ff,$06,$00,$01,$ff,$03,$00
fcb $01,$ff,$01,$00,$01,$ff,$02,$00,$01,$ff,$02,$00,$01,$ff,$01,$00
fcb $01,$ff,$0b,$00,$01,$ff,$05,$00,$01,$ff,$01,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$03,$ff,$01,$00,$01,$ff,$01,$00
fcb $01,$ff,$0b,$00,$01,$ff,$05,$00,$01,$ff,$04,$00,$01,$ff,$02,$00
fcb $01,$ff,$01,$00,$01,$ff,$02,$00,$01,$ff,$02,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$03,$00,$01,$ff,$40,$00,$01,$ff,$06,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$02,$ff,$03,$00,$01,$ff,$02,$00
fcb $01,$ff,$01,$00,$01,$ff,$0a,$00,$01,$ff,$06,$00,$02,$ff,$02,$00
fcb $03,$ff,$01,$00,$03,$ff,$01,$00,$02,$ff,$0b,$00,$01,$ff,$07,$00
fcb $01,$ff,$03,$00,$01,$ff,$02,$00,$02,$ff,$03,$00,$01,$ff,$02,$00
fcb $02,$ff,$02,$00,$02,$ff,$03,$00,$01,$ff,$3f,$00,$01,$ff,$06,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$02,$00
fcb $01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff,$09,$00,$01,$ff,$07,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$0d,$00,$01,$ff,$07,$00
fcb $01,$ff,$02,$00,$01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff,$02,$00
fcb $01,$ff,$02,$00,$01,$ff,$03,$00,$01,$ff,$05,$00,$01,$ff,$3d,$00
fcb $03,$ff,$06,$00,$02,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00
fcb $03,$ff,$01,$00,$02,$ff,$0a,$00,$03,$ff,$05,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$01,$ff,$01,$00
fcb $01,$ff,$01,$00,$01,$ff,$0b,$00,$02,$ff,$06,$00,$02,$ff,$03,$00
fcb $01,$ff,$02,$00,$01,$ff,$01,$00,$01,$ff,$01,$00,$03,$ff,$01,$00
fcb $01,$ff,$03,$00,$03,$ff,$01,$00,$02,$ff,$ff,$00,$ff,$00,$ff,$00
fcb $43,$00,$00
+174
View File
@@ -0,0 +1,174 @@
# Sound Lab coverage and remaining acceptance
This is an initial diagnostic disk and listening toolkit, not completion of the
entire Sound Lab specification. The current set contains 114 authored vectors
with vector-set CRC `62E5`. Adding more vectors will require an explicit vector
revision and renewed artifact receipts; existing reports must remain attributable
to their original bytes.
Reference: **Sound Lab shared CoCo Sound/Speech diagnostic specification**,
Revision 1, November 17, 2026, repository blob
`8b2b303cfce4a3a7e4d1bf377b6a8fca68e62b16`:
[original specification](https://vccplus-git.brianholman.com/VCCPlus/Coco3FPGAResearch/src/branch/codex/timing-de1-investigation/docs/VCC_SSC_DIAGNOSTIC_SPEC.md).
## How to interpret the coverage
**Implemented packet** means an authored packet exists and passes the host's
grammar/identity checks. **Partial** means only part of a specified activity is
implemented. **Deferred** means it cannot be accepted using this disk's current
cases. None of these labels means Brian heard a sound, that a physical cartridge
passed, or that the FPGA implementation is correct.
Vector subcase IDs distinguish individual packets from whole specification
chapters. For example, `BUF01-SP1` addresses speech slot 1; it does not prove
the full `BUF01` overwrite-isolation/sharing requirement. `ALP01-01` is just
pause address 1 within the specification's 64-address `ALP01` chapter. The
mappings below are authoritative for this initial set.
The seven-case showcase is `TXT01`, `TON01-A`, `TON04`, `TON05`, `NOI01`,
`FUN01-TUNE`, `MIX01`. The guided group has 14 cases. The engineering group and
individual case selector expose the other packets. The engineering menu currently
still asks for a human response after each case; it is not an unattended sweep.
Duration targets of three minutes and 10–15 minutes depend on listener responses
and have not been qualified as fixed-duration experiences.
## Specification-to-implementation matrix
| Specification ID | Current implementation / local vector IDs | Remaining requirement and acceptance |
| --- | --- | --- |
| SET01 | **Partial.** Guest asks target, CoCo model, NTSC/PAL and disk/screen-only mode; user confirms normal speed and configured cartridge. Existing SDK routing token is saved/restored. No floating-status auto-detection or MPI bank changes. | Cartridge model/modification, actual MPI slot arrangement, audio path and emulator/core identity are not all collected as structured guest fields. Record these in accompanying run notes. Physical routing/interrupt preservation still needs observation. |
| RST01 | **Partial infrastructure.** Startup uses FF7D=1 then0; subsequent output has bounded ready polling. | No separately recorded cold-reset test, startup status timeline or reset-silence listening result. A click or sustained sound cannot be inferred from a later ready bit. |
| TXT01 | **Implemented packet.** Exact original greeting, followed by explicit space/CR; replay and HUMAN score supported. | Native/emulated execution evidence and real-card listening are separate. Record recognizability; do not substitute modern text-to-speech pronunciation. |
| TXT02 | **Partial.** `TXT02-READ` says an authored sentence with words and spelled-out numbers; exact ASCII is in manifest. | Minimal pairs, digit-character cases and an actual countdown are not implemented. |
| TXT03 | **Partial.** `TXT01`/`TXT03-LONG` provide different sentence lengths and manual replay. | Exact lengths 1/31/62, delayed submission, firmware boundary behavior and maximum-capacity qualification are not tested. Host rejection of oversized packets is not a firmware acceptance test. |
| ALP01 | **Implemented packet series.** Local `ALP01-00`–`ALP01-63` request all 64 addresses independently, label each and explain addresses 0–4 as silent pauses; final pause and FF included. | Group navigation is sequential cases, not an authored small-group lesson. All pronunciation, pause timing and physical listening remain unqualified. |
| ALP02 | **Deferred.** Individual codes do not make a word-comparison activity. | Add original hand-authored words versus equivalent text words, exact code arrays, repeated A/B playback and optional blind transcript reveal. |
| BUF01 | **Partial.** `BUF01-SP0`–`BUF01-SP7` independently load and execute all eight text slot addresses using unique spoken labels. | These cases do not prove retained neighbors, overwrite isolation, repeated playback without reload, or text/allophone sharing. Add one multi-step script that loads all slots, replays them, overwrites one, and replays its neighbors without reloading. |
| BUF02 | **Partial.** `BUF02-SN0`–`BUF02-SN7` independently load and execute all eight sound slot addresses with distinct pitches. | No semantic sound-slot isolation or simultaneous speech-buffer independence proof. Load all first, replay without reload, overwrite one and verify unchanged neighbors and stored speech. |
| CMD01 | **Partial.** Immediate text, stored text, sound, allophone and direct-register packets exist. Local `CMD01` sends C7/CF/00. `TIM01` sends 8F. | No chained-buffer vectors, stored-register B8–BF/F8–FF execution vectors, stop/retain/replay sequence, reload recovery lesson, or dedicated command-family equivalence assertions. FF boundary/data handling is tested on the host and has `REG02`/`TIM02` guest packets. |
| TON01 | **Implemented packet components.** Local `TON01-A`/`TON01-B`/`TON01-C` independently exercise A/B/C with period 254 and amplitude 10; `TON05` is a three-voice chord. | Requires actual execution/listening and comparative measurements. These are three mono voices, not three stereo positions. |
| TON02 | **Partial.** `TON04` steps through periods 428/339/254. | Specified 250/500/1000 and engineering boundaries 1/4095 are absent. The channel B packet is `TON01-B`; it does not stand in for this pitch ladder. |
| AMP01 | **Partial.** Local `AMP01` uses amplitudes 2/5/9/13 at one pitch, followed by explicit silence. | Exact ladder 0/1/4/8/12/15 with zero-volume rest and repeat is absent. No linear-loudness or equal-gain assertion is made. |
| NOI01 | **Partial.** Local `NOI01` uses noise A periods 1/8/31; `NOI02` exercises retain-previous-amplitude bit. | Noise B/C, periods 0/16, percussion lesson and tone-plus-noise mixer cases are absent. Analog noise is not expected to be sample-identical across devices. |
| ENV01 | **Partial.** `ENV01-00`–`ENV01-15` request every shape with documented tone/envelope ordering and explicit final silence. | All use one envelope period and one channel. Short/long comparison, retrigger during playback, two-channel sharing and richer A/B descriptions are absent. `ENV01-10` belongs to the guided group; the other 15 shapes are engineering cases. |
| REG01 | **Partial.** `REG01` programs toneA fine/coarse, mixer and fixed amplitude through AF; `REG02` includes legal FF register data. | Direct envelope/multi-channel/mixer isolation matrix is absent. No unsupported AY register readback is invented. |
| TIM01 | **Partial.** Local `TIM01` sets base 16 and plays one finite tone; `TIM02` uses duration FF. | No controlled multi-duration/multi-base matrix, precise note-on/off timestamps or repeated-gap distributions. A declared timer baseline is required between cases; coarse guest ticks are not calibrated audio timing. |
| STS01 | **Partial infrastructure.** Guest records full status before/after, transmitted-byte count, elapsed VSYNC ticks and whether a wait-mask busy state was observed. | No continuous transition timeline, startup/decay latency distribution or calibrated polling resolution. A missed pulse is unresolved, not evidence of no pulse. Status 40/20 meanings remain source/hardware qualification work. |
| MIX01 | **Partial.** `TXT01`, tone cases and local `MIX01` offer speech alone, sound alone and a held tone under an authored phrase; bounded global cleanup stops both. | No independent speech-stop versus sound-stop listening sequence or structured clipping/dropout comparison. Held-tone cleanup must be confirmed in execution. |
| MUX01 | **Deferred.** Routing is set on entry and restored on exit. | No mid-play cartridge mux/speaker gating exercise, inaudible-progress comparison or normal CoCo SOUND/DAC regression. Entry/exit restoration is not equivalent to this test. |
| RST02 | **Partial safety infrastructure only.** Timeout/interrupted packets reset before recovery. | No deliberate active-tone, active-speech, combined-play or incomplete-load reset cases with independently recorded recovery and explicit buffer reinitialization. |
| REP01 | **Deferred.** The user can repeat a selected case. | No numbered repeated speech sequence covering cumulative 4096 speech samples, no stale-ring/frozen-speech detector. A guest cannot read internal speech sample counts. |
| REP02 | **Deferred.** Sequential engineering cases have deterministic order and bounded waits. | No timed 60-second/5-minute alternating stress script, unattended mode or qualified drift measurement. |
| FUN01 | **Partial experience.** Local `FUN01-TUNE` plays an original finite tune with note-off; greeting and other labels are separate cases. | No interactive musical keyboard or spoken note labels. Local ID does not satisfy the whole proposed activity. |
| FUN02 | **Partial ingredients.** `TON05`, `NOI01`, `FUN01-TUNE` and `MIX01` supply chord/noise/tune/spaceport-message components. | No integrated countdown, layered engine, launch motif, radio message, landing chime and final quiet timeline. Local `MIX01` is a short finale, not the full scene. |
| ORC01 | **Deferred optional extension.** No FF7A/FF7B packets are sent. | Separate Orchestra-90 profile and left/right tests may follow. Not applicable to SSC-only acceptance; SSC is mono. |
| EXT01 | **Deferred MiSTer integration.** No extended-video-palette operations are performed. | FPGA team must test its bus ownership/graphics/ordinary sound/Orchestra interactions. Not applicable to a plain physical SSC. |
## Other specification requirements
The build produces ordinary 6809 `.BIN`, Disk BASIC `.BAS`, 35-track raw `.DSK`,
SHA-256 artifact receipts and the exact vector manifest. The same guest bytes
can be copied to each target; platform selection only changes report metadata.
The guest has no network, OS-9, GUI debugger or emulator-private API dependency.
The guest polls once per actual bus read, waits before each byte, uses a VSYNC
deadline plus an independent iteration limit, and resets after partial-packet
failure. These paths exist in source. Their presence is distinct from proving
all timeout, panic, IRQ-mask, PAL, counter-wrap and recovery behavior on hardware.
The test never selects a faster physical CoCo clock. A speed comparison is not
part of this initial disk.
Disk reports use unique names, CRLF, per-case flushes, explicit partial/complete
footers, record counts and CRCs. Screen-only mode and RAM paging are present.
The bounded RAM report can span multiple report files; preserve all files for a
run session. The host extractor/parser compares build/vector identities and
keeps AUTO and HUMAN outcomes separate. The initial guest records observations,
not automatic hardware PASS. Complete physical disk-full/write-protect/retry,
interrupted-report, no-disk and photograph usability checks remain acceptance
work. Host synthetic filesystem fixtures do not prove a real drive's behavior.
The optional WAV analyzer accepts manually marked intervals, measures basic
PCM levels, isolated-tone crossings, clipping and repeated-case differences.
Automatic case-marker alignment, spectrum comparison, calibrated capture-clock
tolerances and full audio timeline integration remain deferred. WAV generation
from an emulator is not a physical recording, and a text report is not audio.
The specification's comprehensive chip-internal suite and timestamped PIC/AY/SP
tracing are a separate deferred engineering effort. The initial native runner
can exercise actual emulator DOS boot, selected guest interactions, report disk
writes, signal presence and absent-card recovery. It does not implement all
timer/IRQ/DDR/cycle-debt, ROM-loader, ALD/DRQ, envelope/noise, coefficient/filter
saturation tests or negative-control fault injections requested in that section.
Existing unrelated SSC tests must be cited individually before reusing their
evidence; they are not silently counted as completion of this disk's spec.
## Verification layers and evidence limits
1. **Source/packet checks:** six vector host tests passed during initial authoring,
including CCITT-FALSE reference value, malformed packets, FF operand handling,
all slots/codes/shapes, deterministic outputs and selected fixed vector CRCs.
The source catalog records a hashed OCR/typeset Tandy reproduction whose
command-table pixels were inspected. Original photographic scan comparison
remains pending. Successful validation proves the declared packet structure
and identity, not firmware execution or audible fidelity.
2. **Native/emulated checks:** use the coordinator's final build/test receipt for
exact artifact hashes, source revision and actual results. A compiled runner
or generated disk alone is not a passed test. Signal detection must stay
separate from HUMAN listening. Any emulator findings describe the current
comparison baseline; they do not revise physical expectations to fit it.
3. **Physical acceptance:** not performed by this coverage review. Brian must
boot this exact disk on a real CoCo, listen/repeat, save/reload reports and
verify safe recovery. Physical Intel/macOS testing is unrelated to the CoCo
cartridge's analog behavior.
4. **FPGA acceptance:** pending research-core availability and its pre-install
checks. Use the same disk/vector identities, identify stock versus research
cores, and compare observations with the physical baseline. VCC-only success
cannot stand in for real-card or MiSTer acceptance.
No speech/sound engine, SDK or application implementation change is authorized
by this document. The emulator baseline remains unchanged while FPGA work is
finished and recommendations are reviewed.
## Next checks for Brian and the FPGA project
1. Keep an unchanged master disk and manifest. Use a fresh writable copy per
platform; verify its starting SHA-256 before first use. After testing, retain
the changed disk and all `SNDxxxx.TXT` files rather than comparing its modified
hash to the pristine artifact hash.
2. Record CoCo model, NTSC/PAL, normal speed,26-3144/3144A/unknown cartridge,
known modifications, MPI/disk slots, speaker/audio path and emulator or FPGA
build identity. Do not guess physical ROM hashes. No hardware modification
or cartridge hot-swap is required.
3. Boot with `DOS` on VCC Plus and a real CoCo. Run **Meet the Robot** at low
volume. Score each case, repeat `TXT01`, mark an intentionally uncertain
result, add a note and confirm each sound stops. The current seven cases are
listed above; missing full-spec scenes must not be marked complete.
4. Quit normally, relaunch and run again. Verify a new report filename is used.
Safely copy the disk, extract reports, convert them using the matching build
manifest, and verify their checksum/count/footer and build/vector identities.
Keep actual VCC and physical reports together with any photographs/recordings.
5. Select individual `REG01`, `REG02`, `TIM02`, representative envelope cases
and `ALP01-00`–`ALP01-04`. Confirm legal FF operands do not terminate early, held
tones end at cleanup, pause cases are intentionally quiet, and no physical
timeout threshold is inferred from the emulator's observed count.
6. Exercise **X** during an audible wait and confirm a bounded return to menu;
repeat `TXT01` afterward. With no SSC configured, run screen-only mode and
confirm bounded handling/no false detected-card claim. Preserve any timeout
or interrupted report instead of treating it as a pass.
7. On disposable media only, separately test screen-only, write-protected or
full disk, retry-save, RAM paging and interrupted-run report extraction.
Confirm the app never formats a disk or overwrites an earlier run. A full
RAM report may need a new file/run; save or photograph before clearing.
8. If recording audio, use fixed gain and preferably 48 kHz/16-bit PCM with lead-in
and trailing silence. Mark exact intervals manually, retain the raw WAV and
capture notes, and compare measured changes without demanding identical
analog waveforms or absolute loudness. Record human judgments independently.
9. Give the FPGA team the same pristine disk, `.BIN`/`.BAS`, full manifest,
parser/analyzer, this coverage map and actual physical reports. Run first on
the separately identified research core after its own build/pre-install
checks. Report discrepancies without modifying the emulator baseline.
10. Expand deferred tests deliberately: first buffer isolation/sharing and reset
recovery; then exact tone/amplitude/noise/timing matrices; then mux controls,
stress runs and chip-internal negative controls. Address the ID mapping
explicitly in that next vector revision, preserving subcase suffixes so an
individual packet cannot be mistaken for a complete specification chapter.
+161
View File
@@ -0,0 +1,161 @@
# Sound Lab — diagnostic disk
Sound Lab is a standalone, keyboard-driven CoCo program for comparing the Tandy
Speech/Sound Cartridge in VCC Plus, on a real CoCo, and eventually in the research
FPGA core. It does **not** change VCC Plus's speech/sound implementation. This
first disk provides a useful listening baseline; [coverage](COVERAGE.md) identifies
the larger diagnostic specification's remaining work explicitly.
## Start here
Keep `SOUNDLAB.DSK` as an unchanged master. Make a **writable copy** for each test
environment. The disk is ordinary single-sided Disk BASIC: 35 tracks, 18 sectors
per track, 256 bytes per sector, 161,280 bytes in total. No cartridge ROM is in
the disk or delivery archive.
1. Use a 64-KiB-or-larger CoCo, Disk BASIC, a Speech/Sound Cartridge and **normal
CPU speed**. Start with low speaker volume. In VCC Plus, use Disk BASIC with
the Speech/Sound Cartridge configured. Do not use an OS-9 preset.
2. Insert the writable disk in **FD0**, then type `DOS` and press Return.
Alternatively type `RUN"SOUNDLAB"`. The supplied BASIC loader uses `PCLEAR1`
and `CLEAR32` before loading the machine-language program at `$1600`.
Do not bypass that setup with a bare `LOADM` in an arbitrary existing session.
3. Choose the platform, CoCo model and NTSC/PAL setting. These are descriptions,
**not automatic cartridge detection**. Confirm your own physical cartridge,
MPI arrangement and speaker path separately. The program does not switch MPI
banks or enable double-speed mode.
4. Choose **D** to save reports to the writable FD0 copy, or **M** for screen-only
operation. Use the diagnostic disk, never an important software/data disk.
5. Start **1 — Meet the Robot**. The brief showcase includes a greeting, a tone,
rising notes, a chord, noise, a small original tune and a spaceport voice.
**2** selects more guided examples. **3** requires explicit confirmation for
the larger engineering set. **4** runs a case ID from the manifest.
Disk loading and simultaneous cartridge use require compatible hardware routing,
usually a Multi-Pak plus disk controller. Do not hot-swap powered cartridges to
work around a single cartridge slot. Screen-only mode suppresses report disk I/O;
it does not invent a new way to load the program.
## Listen, repeat and recover
Read the listening prompt, then press **Return** to play (or **X** for the menu).
Each result waits for your response:
| Key | Meaning |
| --- | --- |
| H | Heard the expected example |
| W | Heard something wrong |
| N | No sound |
| U | Unsure |
| R | Record this attempt and repeat the example |
| S | Skip |
| T | Add a short note, then choose a result |
| X | Return to the menu; also interrupts bounded playback waits |
The first five allophone addresses are **pauses**: silence is intentional.
Three AY tone channels mix to mono; they are not three stereo positions. A saved
`AUTO=OBSERVED` describes register/timing observations, not successful listening.
Only your response supplies `HUMAN=HEARD`. Test timing is in video-frame ticks;
PAL/NTSC, polling overhead and firmware latency prevent treating it as calibrated
audio duration. Analog tolerances remain `MEASURE_BASELINE`.
Sound Lab resets the cartridge at each case's beginning to establish a consistent
timer/buffer baseline. It records that prelude separately from the vector bytes.
It sends the documented stop-both command after each case, or resets after an
interrupted/unfinished packet or timeout. The cartridge's stored buffers are
diagnostic scratch space. **Q** saves the final report, resets the cartridge and
returns to BASIC with the saved PIA audio routing restored. It leaves the CPU
speed and MPI selection alone. The loader's text mode/graphics-page allocation
is part of this standalone program, not a preserved running CoCo application.
## Reports
The program reserves unused `SND0001.TXT`, `SND0002.TXT`, … filenames. Existing
reports are never intentionally replaced. It flushes observations **between**
cases, not during sound playback. The small CoCo RAM log rolls into additional
numbered files; retain **all** of them. The displayed attempt number is a session
sequence and distinguishes repeats and later re-selection of the same case.
Keep the disk inserted during a session. Before updating a checkpoint, the
program checks the saved file's bytes against its prior checkpoint. A changed or
swapped file is refused with error250. Disk errors leave the current RAM log
available: use **5** to page/photograph it, or **6** to retry saving after fixing
the original media problem. A partially failed physical write may require keeping
the RAM photographs rather than retrying over an uncertain file. Do not swap a
different disk into the open report. No formatting or repair is attempted.
In screen-only mode, a full log pauses before the next case. Photograph its
pages before explicitly choosing **C** to clear it for another report segment.
**X** keeps it and returns to the menu. There is no silent log eviction.
Safely save/eject the disk in VCC Plus, or transfer the physical disk image using
your normal hardware workflow. Work from a saved host copy:
```sh
python3 host/soundlab_reports.py extract MYTEST.DSK --output extracted
python3 host/soundlab_reports.py convert extracted/SND0001.TXT \
--output readable --manifest SOUNDLAB-manifest.json
```
See [host report instructions](host/README.md) for comparison and JSON/CSV/HTML
exports. Keep the original modified DSK, raw TXT files, manifest and any WAVs or
photographs. The pristine disk hash changes when reports are saved; this is
expected and does not invalidate the original build receipt.
Optional [WAV analysis](audio/README.md) accepts manually marked intervals and
measures signal levels, clipping and qualified isolated-tone estimates. It never
relabels measurements as human listening or analog hardware acceptance.
## Rebuild and validate
In the VCC Plus repository:
```sh
python3 examples/sound-lab/build.py
python3 -m unittest discover -s examples/sound-lab/tests -v
```
For the isolated real-ROM run, use the retained core library and explicit private
ROM folder (these inputs are never copied into the delivery):
```sh
python3 examples/sound-lab/check.py \
--core .build/371-release-native/Build/Products/Release/libVCCCore.a \
--roms platforms/macos/LocalResources/ROMs
```
The default output is `.build/sound-lab`. An exported project accepts explicit
`--toolchain /path/to/Toolchain --output /path/to/new-build` arguments. Use the
bundled VCC Plus toolchain, **CMOC0.1.101**, with its matching LWTools, SSC and
public-domain `decbfile` libraries. The supported driver uses ordinary Disk BASIC
ROM services; no separately licensed standalone disk driver is copied here.
Python is only a build/reporting dependency on the host, not on the CoCo.
`SOUNDLAB-manifest.json` binds the short guest build ID and vector CRCs to full
source/artifact SHA-256 hashes. `SHA256SUMS` covers the BIN, BASIC loader and DSK.
The host BASIC source uses LF; its disk member uses the disk writer's explicit
leading-CR and CR line-ending conversion. Both forms contain the same loader.
The compiler's `$7A00` limit and retained map check ordinary memory bounds. The
text-only guest uses the otherwise unused, `PCLEAR1`-reserved PMODE page at
`$0E00–$13FF` as a1536-byte log. Compiled assembly is checked for one actual
`LDB $FF7E` per status-reader call. Ready and completion loops have elapsed-tick
and independent iteration limits.
The [native runner](native/run.cpp) boots the disk through actual Disk BASIC and
FD502 emulation with existing private local ROM inputs. It does not launch or
operate the user's app. The build receipt records what was tested. Physical CoCo
listening, physical disk behavior and future FPGA acceptance remain separate.
## Sources and license
Sound Lab guest, generator, original vectors, host utilities and tests are
GPL-3.0-or-later, like the VCC Plus SDK. The tiny DOS bootstrap retains Pierre
Sarrazin's public-domain attribution. CMOC library/dependency notices remain in
the toolchain distribution; this project does not redistribute the compiler or
private firmware. The delivery's `COPYING` is the GPL license text.
[Packet/source notes](vectors/PROTOCOL.md) cite a downloaded, hashed OCR/typeset
reproduction of Tandy's original publication. It is not a photographic scan.
The diagnostic bytes are newly authored; manual PDFs and ROM contents are not
included in the disk or source archive. No checksum establishes redistribution
rights or proof of hardware fidelity.
+118
View File
@@ -0,0 +1,118 @@
# Optional audio measurements
`analyze.py` measures a pre-existing uncompressed integer PCM WAV with Python
3.9 or later and no extra packages. It does not capture audio, operate an emulator,
change a cartridge, or identify hardware. Keep the raw WAV and its interval
manifest as evidence; the report includes SHA-256 digests of both inputs.
```sh
python3 examples/sound-lab/audio/analyze.py capture.wav intervals.json --output measurements.json
```
Reports go to standard output when `--output` is absent. Existing report files
are protected; `--overwrite` explicitly replaces a report, but cannot replace
either input. No command modifies the WAV or manifest. These potentially large
and private recordings belong outside Git.
## Capture and interval preparation
Use an external line-level recorder or the platform's audio export. Ideally
record uncompressed **48 kHz, 16-bit PCM**, with a fixed gain and without AGC,
noise suppression, equalization or other processing. Record lead-in and trailing
silence. Record the connection path (real analog, emulator export, HDMI or other),
gain, cartridge/configuration and any resampling in your own capture notes.
WAV header values describe the file; they do not calibrate a real capture clock.
Use displayed/counted markers or an optional marker sound outside measured
windows to locate each case. Enter actual offsets into the manifest after
reviewing the recording. Guest counters and marker ticks do **not** necessarily
coincide with audio sample boundaries. This analyzer does not infer markers or
align recordings automatically.
```json
{
"capture_context": {
"source": "real analog — user reported, not verified",
"gain_notes": "fixed recorder gain; no AGC",
"marker_notes": "start measured manually after the count-in"
},
"segments": [
{
"case_id": "TONE-EXAMPLE",
"vector_id": "exact-vector-identity-from-run",
"kind": "tone",
"start_seconds": 1.25,
"end_seconds": 3.25,
"nominal_hz": 440.0
}
]
}
```
A top-level array of segment objects is also accepted. Each segment requires a
nonempty `case_id`, explicit finite `start_seconds` and `end_seconds`, and a
`kind` of `tone`, `noise`, `speech` or `silence`. Overlapping windows are allowed
for deliberate analysis of the same samples. Windows must be within the file
and contain at least one sample. Samples with timestamps `start <= n/rate < end`
are included. Reports retain requested offsets, zero-based start/exclusive stop
frames, PCM payload byte offsets and actual sample-window duration. Byte offsets
refer to decoded PCM payload, **not** offsets into the WAV container.
`vector_id` is optional for individual measurements, but required for repeated
case comparison. Use the exact vector identity or CRC from the guest run. Only
matching `case_id`, `vector_id` and `kind` are compared; matching labels are
user assertions, not independently proven guest provenance.
## Meaning and limits
The analyzer supports `WAVE_FORMAT_PCM` with 8-bit unsigned and 16/24/32-bit signed
integer PCM. It rejects compressed, floating-point or extensible-format WAV,
truncated payloads and unsupported sample widths. Convert unsupported containers
explicitly and preserve both the original and conversion notes. Channels are
measured independently without mixing or resampling.
RMS, AC RMS, peak and DC offset are normalized to signed full scale. The
`clipping_count` counts exact positive/negative PCM rails; reaching a rail is
evidence to inspect, not proof of a defective device. `near_zero_ratio` counts
samples within one LSB of digital zero; it is not a perceptual silence threshold.
For `tone` only, a frequency estimate uses linearly interpolated upward zero
crossings after removing the window's mean DC offset. At least three crossings
are required. The report includes crossing-period variation. This is appropriate
for an isolated pure tone: harmonics, noise, clipping, modulation and transients
can create extra crossings or bias the fundamental. Review the signal and window
before interpreting an estimate. No frequency estimate is made for noise or
speech, and silence cannot establish an output-stage fault.
The default assessment is `MEASURE_BASELINE` with observations `OBSERVED` and
human listening `NOT_OBSERVED`. No measured value establishes `HEARD`, general
success, analog waveform equality, real hardware identity or accurate clocks.
Repeated-case reports give differences, without an automatic pass/fail judgment.
Keep human listening results separate in the diagnostic run report.
If a qualified frequency tolerance has independently been established, a tone
segment with `nominal_hz` may additionally specify:
```json
"frequency_tolerance": {
"absolute_hz": 2.0,
"qualification": "Example only: replace with the documented hardware/clock basis and reference"
}
```
This enables a **measurement-only** `WITHIN_QUALIFIED_TOLERANCE` or
`OUTSIDE_QUALIFIED_TOLERANCE` assessment on that channel when frequency can be
estimated. It does not certify the supplied justification or convert an
observation into a listening or compatibility pass. The report as a whole remains
`MEASURE_BASELINE`. Do not invent tolerances from an arbitrary passing run.
## Portable checks
From the repository root:
```sh
python3 -m unittest discover -s examples/sound-lab/tests -p test_audio.py -v
```
Tests author their own temporary WAVs, including tones at both 44.1 and 48 kHz,
silence, integer rails, different stereo channels and malformed inputs. They
verify measurements and input preservation, not audible quality or hardware.
+273
View File
@@ -0,0 +1,273 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Measure explicitly identified Sound Lab intervals; never infer listening success."""
import argparse
import hashlib
import io
import json
import math
from pathlib import Path
import statistics
import sys
import wave
KINDS = {"tone", "noise", "speech", "silence"}
def finite_number(value, label):
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
raise ValueError(label + " must be a finite number")
return float(value)
def sha256(data):
return hashlib.sha256(data).hexdigest()
def load_pcm(path):
"""Return integer samples and the capture's declared format, without resampling."""
raw = Path(path).read_bytes()
# New Python versions also accept IEEE float through wave. Enforce the same
# integer-only, portable WAVE_FORMAT_PCM contract on every supported Python.
if len(raw) < 12 or raw[:4] != b"RIFF" or raw[8:12] != b"WAVE":
raise ValueError("expected a little-endian RIFF/WAVE file")
offset = 12
format_tag = None
while offset + 8 <= len(raw):
size = int.from_bytes(raw[offset + 4:offset + 8], "little")
if raw[offset:offset + 4] == b"fmt ":
if size < 16 or offset + 8 + size > len(raw):
raise ValueError("invalid WAV format chunk")
format_tag = int.from_bytes(raw[offset + 8:offset + 10], "little")
break
offset += 8 + size + (size % 2)
if format_tag != 1:
raise ValueError("only WAVE_FORMAT_PCM integer WAV is supported; convert compressed, float or extensible WAV explicitly")
try:
with wave.open(io.BytesIO(raw), "rb") as source:
if source.getcomptype() != "NONE":
raise ValueError("only uncompressed integer PCM WAV is supported")
width = source.getsampwidth()
channels = source.getnchannels()
rate = source.getframerate()
frames = source.getnframes()
if width not in (1, 2, 3, 4):
raise ValueError("supported PCM widths are 8, 16, 24 and 32 bits")
if rate <= 0 or channels <= 0 or frames <= 0:
raise ValueError("WAV must contain samples at a positive rate")
payload = source.readframes(frames)
except (wave.Error, EOFError) as error:
raise ValueError("unsupported or invalid PCM WAV: " + str(error)) from error
if len(payload) != frames * channels * width:
raise ValueError("truncated WAV sample data")
samples = [[] for _ in range(channels)]
for index in range(0, len(payload), width):
value = int.from_bytes(payload[index:index + width], "little", signed=width != 1)
if width == 1:
value -= 128
samples[(index // width) % channels].append(value)
return samples, {
"filename": Path(path).name, "sha256": sha256(raw), "byte_count": len(raw),
"sample_rate_hz": rate, "channels": channels, "bit_depth": width * 8,
"frame_count": frames, "duration_seconds": frames / rate,
"format": "uncompressed integer PCM", "sample_rate_source": "WAV header; not clock calibration",
}
def validate_manifest(document, info):
if isinstance(document, list):
segments = document
elif isinstance(document, dict):
segments = document.get("segments")
else:
segments = None
if not isinstance(segments, list) or not segments:
raise ValueError("manifest must contain a nonempty segments list")
checked = []
for index, segment in enumerate(segments):
label = "segment " + str(index)
if not isinstance(segment, dict):
raise ValueError(label + " must be an object")
case_id = segment.get("case_id")
if not isinstance(case_id, str) or not case_id.strip():
raise ValueError(label + " needs a nonempty case_id")
if segment.get("kind") not in KINDS:
raise ValueError(label + " has unsupported kind")
start = finite_number(segment.get("start_seconds"), label + " start_seconds")
end = finite_number(segment.get("end_seconds"), label + " end_seconds")
if start < 0 or end <= start or end > info["duration_seconds"]:
raise ValueError(label + " interval must satisfy 0 <= start < end <= WAV duration")
# Samples at timestamps start <= n/rate < end; no implied counter alignment.
first = math.ceil(start * info["sample_rate_hz"])
stop = min(info["frame_count"], math.ceil(end * info["sample_rate_hz"]))
if stop <= first:
raise ValueError(label + " interval contains no sample timestamps")
item = dict(segment)
item.update(start_seconds=start, end_seconds=end, start_frame=first, stop_frame=stop)
vector_id = item.get("vector_id")
if vector_id is not None and (not isinstance(vector_id, str) or not vector_id.strip()):
raise ValueError(label + " vector_id must be a nonempty string when supplied")
if "nominal_hz" in item:
nominal = finite_number(item["nominal_hz"], label + " nominal_hz")
if item["kind"] != "tone" or not 0 < nominal < info["sample_rate_hz"] / 2:
raise ValueError(label + " nominal_hz needs a tone below the Nyquist frequency")
item["nominal_hz"] = nominal
tolerance = item.get("frequency_tolerance")
if tolerance is not None:
if not isinstance(tolerance, dict) or "nominal_hz" not in item:
raise ValueError(label + " frequency_tolerance needs nominal_hz")
limit = finite_number(tolerance.get("absolute_hz"), label + " absolute_hz")
qualification = tolerance.get("qualification")
if limit < 0 or not isinstance(qualification, str) or not qualification.strip():
raise ValueError(label + " tolerance needs a nonnegative absolute_hz and qualification")
checked.append(item)
return checked
def tone_estimate(values, rate):
"""Interpolated upward crossings after DC removal, meaningful only for pure tones."""
mean = statistics.fmean(values)
crossings = []
for index in range(1, len(values)):
before, after = values[index - 1] - mean, values[index] - mean
if before < 0 <= after:
crossings.append(index - 1 + (-before / (after - before)))
result = {
"technique": "DC-removed linearly interpolated upward zero crossings",
"limitations": "Pure-tone estimate only. Harmonics, noise, clipping and transients can add crossings or bias the fundamental. No clock calibration is inferred.",
"upward_crossing_count": len(crossings), "estimated_hz": None,
}
if len(crossings) < 3:
result["availability"] = "INSUFFICIENT_CROSSINGS"
return result
periods = [b - a for a, b in zip(crossings, crossings[1:])]
mean_period = statistics.fmean(periods)
result.update(
availability="OBSERVED", estimated_hz=rate / mean_period,
crossing_period_variation_ratio=statistics.pstdev(periods) / mean_period,
measured_span_seconds=(crossings[-1] - crossings[0]) / rate,
)
return result
def channel_metrics(values, bits, rate, segment):
full_scale = 2 ** (bits - 1)
count = len(values)
dc = statistics.fmean(values)
result = {
"rms_full_scale": math.sqrt(sum(value * value for value in values) / count) / full_scale,
"ac_rms_full_scale": math.sqrt(sum((value - dc) ** 2 for value in values) / count) / full_scale,
"peak_full_scale": max(abs(value) for value in values) / full_scale,
"dc_offset_full_scale": dc / full_scale,
"clipping_count": sum(value in (-full_scale, full_scale - 1) for value in values),
"near_zero_ratio": sum(abs(value) <= 1 for value in values) / count,
"near_zero_definition": "absolute signed PCM value <= 1 LSB; a measurement, not an audibility threshold",
"assessment": "MEASURE_BASELINE",
}
if segment["kind"] == "tone":
estimate = tone_estimate(values, rate)
result["frequency"] = estimate
if "nominal_hz" in segment and estimate["estimated_hz"] is not None:
delta = estimate["estimated_hz"] - segment["nominal_hz"]
estimate["nominal_hz"] = segment["nominal_hz"]
estimate["difference_hz"] = delta
tolerance = segment.get("frequency_tolerance")
if tolerance:
estimate["qualified_tolerance"] = tolerance
result["assessment"] = ("WITHIN_QUALIFIED_TOLERANCE" if abs(delta) <= tolerance["absolute_hz"]
else "OUTSIDE_QUALIFIED_TOLERANCE")
return result
def repeated_cases(segments):
groups = {}
for index, segment in enumerate(segments):
if segment.get("vector_id"):
groups.setdefault((segment["case_id"], segment["vector_id"]), []).append(index)
comparisons = []
for (case_id, vector_id), indexes in groups.items():
if len(indexes) < 2:
continue
reference = segments[indexes[0]]
for index in indexes[1:]:
current = segments[index]
if current["kind"] != reference["kind"]:
continue
channels = []
for base, observed in zip(reference["channels"], current["channels"]):
delta = {key + "_difference": observed[key] - base[key]
for key in ("rms_full_scale", "peak_full_scale", "dc_offset_full_scale")}
a = base.get("frequency", {}).get("estimated_hz")
b = observed.get("frequency", {}).get("estimated_hz")
if a is not None and b is not None:
delta["estimated_hz_difference"] = b - a
channels.append(delta)
comparisons.append({
"case_id": case_id, "vector_id": vector_id,
"reference_segment_index": indexes[0], "observed_segment_index": index,
"duration_difference_seconds": current["sample_duration_seconds"] - reference["sample_duration_seconds"],
"channels": channels, "assessment": "OBSERVED",
})
return comparisons
def analyze(wav_path, manifest_path):
samples, info = load_pcm(wav_path)
manifest_bytes = Path(manifest_path).read_bytes()
try:
document = json.loads(manifest_bytes)
except (ValueError, UnicodeDecodeError) as error:
raise ValueError("invalid JSON manifest: " + str(error)) from error
segments = validate_manifest(document, info)
measurements = []
for segment in segments:
first, stop = segment["start_frame"], segment["stop_frame"]
item = dict(segment)
item.update(
sample_count_per_channel=stop - first,
first_sample_seconds=first / info["sample_rate_hz"],
exclusive_stop_seconds=stop / info["sample_rate_hz"],
sample_duration_seconds=(stop - first) / info["sample_rate_hz"],
byte_offset_in_pcm_payload=first * info["channels"] * (info["bit_depth"] // 8),
observation_status="OBSERVED", human_status="NOT_OBSERVED",
channels=[channel_metrics(values[first:stop], info["bit_depth"], info["sample_rate_hz"], segment)
for values in samples],
)
measurements.append(item)
return {
"schema_version": 1, "capture": info,
"manifest": {"filename": Path(manifest_path).name, "sha256": sha256(manifest_bytes)},
"reported_capture_context": document.get("capture_context", {}) if isinstance(document, dict) else {},
"assessment": "MEASURE_BASELINE", "human_status": "NOT_OBSERVED",
"interval_convention": "[start_seconds,end_seconds); include sample timestamps n/rate in that interval; frames are zero based",
"limitations": "Measurements do not establish listening success, hardware identity, calibrated clock accuracy, analog equality or cross-target compatibility. Capture context is supplied by the user, not verified.",
"segments": measurements, "repeated_cases": repeated_cases(measurements),
}
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("wav", type=Path)
parser.add_argument("manifest", type=Path)
parser.add_argument("--output", type=Path, help="JSON output; stdout if omitted; existing files protected")
parser.add_argument("--overwrite", action="store_true", help="explicitly replace an existing report (never an input)")
args = parser.parse_args(argv)
try:
if args.output and args.output.resolve() in (args.wav.resolve(), args.manifest.resolve()):
raise ValueError("report output cannot replace either input")
report = analyze(args.wav, args.manifest)
serialized = json.dumps(report, indent=2, allow_nan=False) + "\n"
if args.output:
with args.output.open("w" if args.overwrite else "x", encoding="utf-8") as output:
output.write(serialized)
else:
sys.stdout.write(serialized)
except (ValueError, OSError) as error:
parser.exit(2, "error: " + str(error) + "\n")
return 0
if __name__ == "__main__":
sys.exit(main())
+78
View File
@@ -0,0 +1,78 @@
#!/usr/bin/env python3
"""Build the standalone 35-track Sound Lab disk using the pinned CMOC bundle."""
# SPDX-License-Identifier: GPL-3.0-or-later
import argparse
import hashlib
import json
import os
from pathlib import Path
import shutil
import subprocess
PROJECT = Path(__file__).resolve().parent
REPO = PROJECT.parents[1]
def digest(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def run(*args, **kwargs):
subprocess.run([str(a) for a in args], check=True, **kwargs)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--toolchain', type=Path, default=REPO/'platforms/macos/LocalResources/ToolchainBundle')
parser.add_argument('--output', type=Path, default=REPO/'.build/sound-lab')
args = parser.parse_args()
output, runtime = args.output.resolve(), args.toolchain.resolve()
if output == PROJECT or PROJECT in output.parents:
parser.error('Choose a build output outside the source project so generated files cannot become source inputs.')
output.mkdir(parents=True, exist_ok=True)
env = dict(os.environ, PATH=str(runtime/'bin')+os.pathsep+os.environ.get('PATH', ''))
version = subprocess.check_output([runtime/'bin/cmoc', '--version'], text=True).strip()
if '0.1.101' not in version:
parser.error('This revision is qualified with CMOC 0.1.101; review a different compiler explicitly.')
assembler = subprocess.check_output([runtime/'bin/lwasm', '--version'], text=True).strip()
if assembler != 'lwasm from lwtools 4.25':
parser.error('This revision is qualified with LWTools 4.25.')
run('python3', PROJECT/'vectors/generate.py', '--output', output/'generated')
vectors = json.loads((output/'generated/vectors.json').read_text())
sources = sorted(p for p in PROJECT.rglob('*') if p.is_file() and '__pycache__' not in p.parts)
source_hash = hashlib.sha256()
for source in sources:
source_hash.update(source.relative_to(PROJECT).as_posix().encode()+b'\0'+source.read_bytes())
build_id = 'SL1-'+source_hash.hexdigest()[:8].upper()
(output/'generated/build.h').write_text(
'#define SOUNDLAB_BUILD "'+build_id+'"\n#define SOUND_VECTOR_SET_CRC16 0x'+vectors['vector_set_crc16']+'\n')
shutil.copy2(PROJECT/'guest/main.c', output/'main.c')
run(runtime/'bin/cmoc', '--coco', '-O2', '--intermediate', '--org=1600', '--limit=7A00',
'--stack-space=1024', '-Igenerated', '-o', 'SOUNDLAB.BIN', 'main.c', '-lssc', '-ldecbfile', cwd=output, env=env)
(output/'SOUNDLAB.BAS').write_bytes(b'10 PCLEAR1:CLEAR 32\n20 LOADM"SOUNDLAB":EXEC\n')
# Public-domain DOS hook by Pierre Sarrazin, retained with its attribution.
# Keep the hook itself as a normal source, with no Makefile parsing at build time.
shutil.copy2(PROJECT/'guest/boot.c', output/'boot.c')
run(runtime/'bin/cmoc', '--dos', '-O0', '--limit=2800', '-o', 'BOOT.BIN', 'boot.c', cwd=output, env=env)
disk = output/'SOUNDLAB.DSK'
disk.write_bytes(b'\xff'*(35*18*256))
run(runtime/'bin/install-coco-boot-loader', disk, output/'BOOT.BIN', env=env)
for name in ('SOUNDLAB.BIN', 'SOUNDLAB.BAS'):
run(runtime/'bin/writecocofile', *(['--newlines'] if name.endswith('.BAS') else ['--binary']), disk, name, cwd=output, env=env)
manifest = dict(vectors, build_id=build_id, compiler=version,
assembler=assembler,
toolchain_manifest_sha256=digest(runtime/'manifest.json'),
libraries=[dict(filename=name,sha256=digest(runtime/'share/cmoc/lib'/name))
for name in ('libssc.a','libdecbfile.a')],
sources=[dict(path=p.relative_to(PROJECT).as_posix(),sha256=digest(p)) for p in sources],
guest_cpu='MC6809', minimum_ram_kib=64, format='DECB 35x18x256',
source_sha256=source_hash.hexdigest(),
artifacts=[dict(filename=name, bytes=(output/name).stat().st_size, sha256=digest(output/name))
for name in ('SOUNDLAB.BIN', 'SOUNDLAB.BAS', 'SOUNDLAB.DSK')])
(output/'SOUNDLAB-manifest.json').write_text(json.dumps(manifest, indent=2)+'\n')
(output/'SHA256SUMS').write_text(''.join(f"{item['sha256']} {item['filename']}\n" for item in manifest['artifacts']))
print(f'Built {build_id}: {disk}')
if __name__ == '__main__':
main()
+40
View File
@@ -0,0 +1,40 @@
#!/usr/bin/env python3
"""Build/check Sound Lab; optional isolated native qualification uses explicit private inputs."""
# SPDX-License-Identifier: GPL-3.0-or-later
import argparse
import os
from pathlib import Path
import subprocess
import sys
PROJECT=Path(__file__).resolve().parent
REPO=PROJECT.parents[1]
def main():
parser=argparse.ArgumentParser(description=__doc__)
parser.add_argument('--toolchain',type=Path,default=REPO/'platforms/macos/LocalResources/ToolchainBundle')
parser.add_argument('--output',type=Path,default=REPO/'.build/sound-lab')
parser.add_argument('--core',type=Path,help='Existing libVCCCore.a; never changes or rebuilds the emulator')
parser.add_argument('--roms',type=Path,help='Private local CoCo3/Disk BASIC/PIC/SP ROM directory; not packaged')
args=parser.parse_args()
if bool(args.core)!=bool(args.roms): parser.error('--core and --roms must be supplied together')
output=args.output.resolve()
env=dict(os.environ,PYTHONDONTWRITEBYTECODE='1')
def run(*command): subprocess.run([str(p) for p in command],check=True,env=env)
run(sys.executable,'-m','unittest','discover','-s',PROJECT/'tests','-v')
run(sys.executable,PROJECT/'build.py','--toolchain',args.toolchain,'--output',output)
assembly=(output/'main.s').read_text()
status=assembly.split('_raw_status\tEQU\t*',1)[1].split('funcend_raw_status',1)[0]
if status.upper().count('LDB $FF7E')!=1:
raise RuntimeError('Generated raw status reader must contain exactly one actual FF7E load')
if args.core:
run('xcrun','clang++','-std=c++17','-O2','-mmacosx-version-min=14.0',
PROJECT/'native/run.cpp',args.core.resolve(),'-o',output/'run')
run(output/'run',args.roms.resolve(),output/'SOUNDLAB.DSK',output/'qualification')
run(sys.executable,PROJECT/'verify_reports.py','--build-dir',output)
else:
print('Native execution SKIPPED: provide --core and --roms for real-ROM qualification.')
if __name__=='__main__': main()
+38
View File
@@ -0,0 +1,38 @@
/* Public domain. Adapted from Pierre Sarrazin's autostart.c 0.1.2 (2018-08-04).
* http://sarrazip.com/ -- Roger Schrag, The Rainbow, Nov 1984, p.140.
* DOS feeds an ordinary Disk BASIC command; no emulator-specific loader.
*/
#include <coco.h>
static byte oldHookInstr;
static word oldHookAddr;
static const char *basicLineReader;
void feedKeyboard(void)
{
word preservedX;
byte nextBasicByte;
asm("stx", preservedX);
*(byte *)0x70=0;
nextBasicByte=*basicLineReader++;
if(!nextBasicByte) {
*(byte *)0x016A=oldHookInstr;
*(word *)0x016B=oldHookAddr;
nextBasicByte='\r';
}
asm {
lda nextBasicByte
ldx preservedX
tfr u,s
leas 4,s
rts
}
}
int main(void)
{
*(byte *)0=-*(byte *)0;
basicLineReader="PCLEAR1:CLEAR32:LOADM\"SOUNDLAB\":EXEC";
oldHookInstr=*(byte *)0x016A; oldHookAddr=*(word *)0x016B;
*(byte *)0x016A=0x7E; *(void **)0x016B=(void *)feedKeyboard;
*(word *)0x2600=0;
asm("jmp", "$ac7c");
return 0;
}
+317
View File
@@ -0,0 +1,317 @@
/* SPDX-License-Identifier: GPL-3.0-or-later
* Sound Lab: ordinary 6809/Disk BASIC guest. No emulator-private API.
* Audio routing uses the existing GPL VCC Plus SSC SDK unchanged.
*/
#include <cmoc.h>
#include <coco.h>
#include <decbfile.h>
#include <vcc/ssc.h>
#include "vectors.h"
#include "build.h"
#define LOG_CAPACITY 1536
/* PCLEAR1 reserves the one unused PMODE page at $0E00..$13FF.
* Sound Lab is text-only; using that page leaves ample native stack space. */
#define logbuf ((char *)0x0E00)
static char linebuf[180], note[49];
static unsigned used, records, checksum, runno=1, route, transmitted, elapsed;
static unsigned saved_used, saved_records, saved_checksum;
static unsigned char saved_complete, have_checkpoint;
static unsigned char disk_mode, created, aborted, timedout, before, after, busy_seen;
static unsigned char disk_error, group, target, video, model;
static unsigned attempt;
static DECBDrive drives[1];
static DECBFile report;
static char filename[13];
static const char *targets[]={"VCCPLUS","REAL_COCO","MISTER"};
static const char *models[]={"COCO3","COCO2_64K","UNKNOWN_64K"};
/* Unlike a C volatile expression, each call really reads the bus once. */
asm unsigned char raw_status(void) { asm { ldb $FF7E } }
asm unsigned ticks(void) { asm { ldd $0112 } }
asm void put_byte(unsigned char value) { asm { ldb 3,s
stb $FF7E } }
static unsigned crc_byte(unsigned crc, unsigned char c)
{
unsigned char bit;
crc ^= (unsigned)c << 8;
for(bit=0;bit<8;++bit) crc=(crc&0x8000)?(crc<<1)^0x1021:crc<<1;
return crc;
}
static void record(const char *s)
{
unsigned n=strlen(s), i;
if(used+n+2>=LOG_CAPACITY) return; /* Caller reserves one full case. */
for(i=0;i<n;++i) { logbuf[used++]=s[i]; checksum=crc_byte(checksum,s[i]); }
logbuf[used++]='\r'; checksum=crc_byte(checksum,'\r');
logbuf[used++]='\n'; checksum=crc_byte(checksum,'\n');
++records;
}
static unsigned char key(void)
{
unsigned char c;
do c=inkey(); while(!c);
return (unsigned char)toupper(c);
}
static void header(const char *title)
{
cls(0); printf("SOUND LAB %s\n%s\n\n",SOUNDLAB_BUILD,title);
}
static void make_name(void) { sprintf(filename,"SND%04u.TXT",runno); }
static unsigned char reserve_report(void)
{
unsigned char err;
while(runno<=9999) {
make_name();
err=decb_createSectorFile(&report,0,filename,DECB_TYPE_ASCII_TEXT,DECB_FORMAT_ASCII);
if(err==DECB_OK) { created=1; return decb_closeSectorFile(&report); }
if(err!=DECB_ERR_ALREADY_EXISTS) return err;
++runno;
}
return DECB_ERR_OUT_OF_SPACE;
}
/* Rewrites only the file reserved by this run, never an existing report.
* RAM remains authoritative after an I/O failure. Close flushes FAT+directory.
* No disk I/O occurs while a test is producing sound.
*/
static void footer_text(char *footer,unsigned char complete,unsigned count,unsigned crc)
{
unsigned n;
sprintf(footer,"ENDRUN=%04u COMPLETE=%s RECORD_COUNT=%u CHECKSUM_CRC16=%04X",
runno,complete?"YES":"NO",count,crc);
n=strlen(footer); footer[n++]='\r'; footer[n++]='\n'; footer[n]=0;
}
static unsigned char save_report(unsigned char complete)
{
char footer[110];
unsigned length, index, offset, i, n;
unsigned char sector[256], err;
unsigned sectors;
dword file_size;
if(!disk_mode) return 0;
if(!created) { err=reserve_report(); if(err) return err; }
footer_text(footer,complete,records,checksum);
length=used+strlen(footer);
err=decb_openSectorFile(&report,0,filename); if(err) return err;
if(have_checkpoint) {
footer_text(footer,saved_complete,saved_records,saved_checksum);
if(decb_getOpenFileSize(&report,&sectors,&file_size)==255 || file_size!=(dword)(saved_used+strlen(footer))) return 250;
for(index=0,offset=0;offset<file_size;++index) {
err=decb_readSector(&report,sector,index); if(err) return err;
n=(unsigned)file_size-offset; if(n>256) n=256;
for(i=0;i<n;++i) if(sector[i]!=(unsigned char)((offset+i<saved_used)?logbuf[offset+i]:footer[offset+i-saved_used])) return 250;
offset+=n;
}
footer_text(footer,complete,records,checksum);
}
for(index=0,offset=0;offset<length;++index) {
n=length-offset; if(n>256) n=256;
memset(sector,0,256);
for(i=0;i<n;++i) sector[i]=(offset+i<used)?logbuf[offset+i]:footer[offset+i-used];
err=decb_writeSector(&report,sector,index);
if(err) { decb_closeSectorFile(&report); return err; }
offset+=n;
}
err=decb_setNumBytesUsedInLastSector(&report,n);
if(!err) err=decb_closeSectorFile(&report);
if(!err) { saved_used=used; saved_records=records; saved_checksum=checksum; saved_complete=complete; have_checkpoint=1; }
return err;
}
static void begin_report(void)
{
used=records=0; checksum=0xFFFF;
created=have_checkpoint=0;
if(disk_mode) disk_error=reserve_report();
make_name();
record("FORMAT=SOUNDLAB-1");
sprintf(linebuf,"RUN=%04u TARGET=%s BUILD_ID=%s VECTOR_SET_CRC16=%04X",runno,targets[target],SOUNDLAB_BUILD,SOUND_VECTOR_SET_CRC16); record(linebuf);
sprintf(linebuf,"MODEL=%s VIDEO=%s SPEED=NORMAL_USER_CONFIRMED",models[model],video?"PAL":"NTSC"); record(linebuf);
record("CARTRIDGE=USER_CONFIRMED_NO_AUTODETECTION");
record("MPI_SLOT=USER_CONFIGURED_NO_BANK_SWITCH");
record("TIMING=VSYNC_TICKS_NOT_AUDIO_SAMPLES");
record("ANALOG_LIMITS=MEASURE_BASELINE");
if(disk_mode && !disk_error) disk_error=save_report(0);
}
/* A tick deadline AND independent iteration bound; X interrupts a wait.
* No claim that an idle bit proves a cartridge is present or audible.
*/
static unsigned char ready_write(unsigned char value)
{
unsigned start=ticks();
unsigned long polls=0;
unsigned char status;
for(;;) {
status=raw_status();
if(status&0x80) { put_byte(value); ++transmitted; return 1; }
if((unsigned)(ticks()-start)>=180 || ++polls>=150000UL) { timedout=1; return 0; }
if((polls&255)==0 && toupper(inkey())=='X') { aborted=1; return 0; }
}
}
static void settle(const SoundVector *v)
{
unsigned start=ticks(), d;
unsigned long polls=0;
unsigned char status;
for(;;) {
status=raw_status();
d=ticks()-start;
if(v->wait_mask && (status&v->wait_mask)!=v->wait_mask) busy_seen=1;
if(d>=v->hold_ticks && (!v->wait_mask || ((status&v->wait_mask)==v->wait_mask && (busy_seen || d>=45)))) break;
if(d>=1800 || ++polls>=1500000UL) { timedout=1; break; }
if((polls&255)==0 && toupper(inkey())=='X') { aborted=1; break; }
}
elapsed=ticks()-start;
}
static void stop_case(void)
{
if(aborted || timedout) ssc_reset(); /* Partial packets require reset. */
else if(!ready_write(0)) ssc_reset(); /* Manual: stop speech + sound. */
}
static void get_note(void)
{
unsigned char c, n=0;
printf("NOTE (48 CHARS, ENTER ENDS):\n");
while((c=key())!='\r') {
if(c==8 && n) { --n; putchar(8); }
else if(c>=32 && c<=126 && c!='\\' && n<48) { note[n++]=c; putchar(c); }
}
note[n]=0;
}
static unsigned char run_case(const SoundVector *v)
{
unsigned i, sent;
unsigned char answer;
unsigned repeat;
const char *human, *automatic;
do {
if(used>LOG_CAPACITY-450) {
if(!disk_mode) {
printf("RAM REPORT FULL. PHOTOGRAPH IT.\nX MENU / C CLEAR FOR NEXT RUN\n");
if(key()!='C') return 0;
}
disk_error=save_report(1);
if(disk_error) { printf("REPORT FULL. SAVE FIRST.\n"); key(); return 0; }
++runno; begin_report();
}
repeat=attempt++;
header(v->id);
ssc_reset(); /* Declared per-case baseline; never inherited timer state. */
printf("%s\n\n%s\n\nX: PANIC / RETURN TO MENU\n",v->title,v->prompt);
printf("\nENTER TO PLAY / X MENU\n");
do answer=key(); while(answer!='\r' && answer!='X');
if(answer=='X') return 0;
printf("PLAYING...\n");
transmitted=elapsed=0; aborted=timedout=busy_seen=0;
before=raw_status();
for(i=0;i<v->length;++i) if(!ready_write(v->tx[i])) break;
sent=transmitted;
if(!aborted && !timedout) settle(v);
after=raw_status();
stop_case();
header(v->id);
printf("ATTEMPT %u CRC %04X TX %u/%u\nSTATUS %02X > %02X TICKS %u\n%s\n\n",
repeat,v->crc16,sent,v->length,before,after,elapsed,aborted?"ABORTED":timedout?"TIMEOUT / RESET":"AUTO: OBSERVED ONLY");
printf("H HEARD W WRONG\nN NO SOUND U UNSURE\nR REPEAT S SKIP\nT ADD NOTE X MENU\n\n");
note[0]=0;
do { answer=key(); if(answer=='T') get_note(); }
while(!strchr("HWNURSX",answer));
human=answer=='H'?"HEARD":answer=='W'?"WRONG":answer=='N'?"NO_SOUND":answer=='U'?"UNSURE":answer=='S'?"SKIPPED":"NOT_OBSERVED";
automatic=timedout?"TIMEOUT":aborted&&!sent?"NOT_RUN":"OBSERVED";
sprintf(linebuf,"CASE=%s VECTOR_CRC16=%04X AUTO=%s HUMAN=%s",v->id,v->crc16,automatic,human); record(linebuf);
sprintf(linebuf,"TX_COUNT=%u TX_EXPECTED=%u TICKS=%u STATUS_BEFORE=%02X STATUS_AFTER=%02X BUSY_SEEN=%s",sent,v->length,elapsed,before,after,busy_seen?"YES":"NO"); record(linebuf);
record("PRELUDE=RESET_01_00 TIMER=RESET_DEFAULT");
sprintf(linebuf,"ABORTED=%s CLEANUP=%s REPEAT=%u",aborted?"YES":"NO",(aborted||timedout)?"RESET":"00",repeat); record(linebuf);
sprintf(linebuf,"NOTE_LENGTH=%u",strlen(note)); record(linebuf);
sprintf(linebuf,"NOTE=%s",note); record(linebuf);
sprintf(linebuf,"ENDCASE=%s",v->id); record(linebuf);
disk_error=save_report(0);
if(disk_error) { printf("DISK ERROR %u: RAM RETAINED\n",disk_error); key(); }
if(answer=='X') return 0;
} while(answer=='R');
return 1;
}
static void show_report(void)
{
unsigned offset=0, rows;
header("FROZEN REPORT");
while(offset<used) {
cls(0); rows=0;
while(offset<used && rows<11) {
unsigned col=0;
while(offset<used && logbuf[offset]!='\r' && col<30) { putchar(logbuf[offset++]); ++col; }
if(offset<used && logbuf[offset]=='\r') offset+=2;
putchar('\n'); ++rows;
}
printf("\nRUN %04u %s\nANY KEY NEXT / X MENU",runno,filename);
if(key()=='X') break;
}
}
int main(void)
{
unsigned i;
unsigned char choice;
width(32);
header("WELCOME, LISTENER");
printf("NORMAL SPEED, 64K+, DISK BASIC\nSSC RAM/BUFFERS WILL BE RESET.\nLOW SPEAKER VOLUME TO START.\n\n1 VCC PLUS 2 REAL COCO\n3 MISTER\n");
do choice=key(); while(choice<'1'||choice>'3'); target=choice-'1';
header("SETUP");
printf("1 COCO 3 2 COCO 2 3 OTHER\n");
do choice=key(); while(choice<'1'||choice>'3'); model=choice-'1';
printf("N NTSC / P PAL\n"); do choice=key(); while(choice!='N'&&choice!='P'); video=choice=='P';
printf("\nD SAVE REPORTS TO THIS FD0\nM SCREEN ONLY / NO DISK I/O\nUSE A DISPOSABLE DISK COPY!\n");
do choice=key(); while(choice!='D'&&choice!='M'); disk_mode=choice=='D';
if(disk_mode) {
disk_error=decb_init(drives,1);
if(!disk_error) disk_error=decb_registerDrive(0);
if(disk_error) disk_mode=0;
}
route=ssc_route_audio();
ssc_reset();
begin_report();
for(;;) {
header("MAIN MENU");
printf("1 MEET THE ROBOT\n2 GUIDED LISTENING LAB\n3 ENGINEERING (OPT IN)\n4 CHOOSE A CASE\n5 VIEW RAM REPORT\n6 RETRY SAVE\nQ SAVE AND QUIT TO BASIC\n\nRUN %04u %s\n%s\n",runno,filename,!disk_mode?"SCREEN ONLY":disk_error?"DISK ERROR / RAM RETAINED":"REPORT SAVED BETWEEN CASES");
choice=key();
if(choice=='Q') {
disk_error=save_report(1);
if(disk_error) { printf("SAVE FAILED. X DISCARD OR RETRY\n"); if(key()!='X') continue; }
break;
}
if(choice=='5') { show_report(); continue; }
if(choice=='6') { disk_error=save_report(0); continue; }
if(choice=='4') {
char id[16]; unsigned char n=0,c;
header("CHOOSE CASE"); printf("CASE ID (UPPERCASE), ENTER:\n");
while((c=key())!='\r') if(n<15 && ((c>='A'&&c<='Z')||(c>='0'&&c<='9')||c=='-')) { id[n++]=c; putchar(c); }
id[n]=0;
for(i=0;i<SOUND_VECTOR_COUNT;++i) if(!strcmp(id,sound_vectors[i].id)) { run_case(&sound_vectors[i]); break; }
if(i==SOUND_VECTOR_COUNT) { printf("\nUNKNOWN CASE. SEE MANIFEST.\n"); key(); }
continue;
}
if(choice<'1'||choice>'3') continue;
group=(unsigned char)(1<<(choice-'1'));
if(group==4) { header("ENGINEERING"); printf("MANY LOUD/REPEATED EXAMPLES.\nLOWER VOLUME. Y CONTINUE\n"); if(key()!='Y') continue; }
for(i=0;i<SOUND_VECTOR_COUNT;++i) if(sound_vectors[i].group&group) if(!run_case(&sound_vectors[i])) break;
}
ssc_reset();
ssc_restore_audio(route);
if(disk_mode) decb_shutdown();
cls(0); printf("SOUND LAB FINISHED\nREPORT %s\n",disk_mode?(const char *)filename:"SCREEN ONLY");
return 0;
}
+157
View File
@@ -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.
+525
View File
@@ -0,0 +1,525 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Read-only Sound Lab Disk BASIC extraction and evidence reporting (stdlib only)."""
from __future__ import annotations
import argparse
import csv
import hashlib
import html
import io
import json
from pathlib import Path
import re
import sys
from typing import Any
DISK_SIZE = 35 * 18 * 256
FAT_OFFSET = (17 * 18 + 1) * 256
DIRECTORY_OFFSET = (17 * 18 + 2) * 256
REPORT_NAME = re.compile(r"SND[0-9]{4}\.TXT", re.IGNORECASE)
KEY = re.compile(r"[A-Z][A-Z0-9_]*")
AUTO = frozenset("PASS FAIL OBSERVED TIMEOUT NOT_RUN NOT_APPLICABLE".split())
HUMAN = frozenset("HEARD WRONG NO_SOUND UNSURE NOT_OBSERVED SKIPPED".split())
class SoundLabError(ValueError):
"""An invalid disk/report or unsafe output operation."""
def crc16(data: bytes) -> int:
"""CRC-16/CCITT-FALSE: polynomial 1021, initial FFFF, no reflection/xor."""
result = 0xFFFF
for value in data:
result ^= value << 8
for _ in range(8):
result = ((result << 1) ^ (0x1021 if result & 0x8000 else 0)) & 0xFFFF
return result
def granule_offset(granule: int) -> int:
track = granule // 2 + (1 if granule >= 34 else 0)
return (track * 18 + (granule % 2) * 9) * 256
def extract_reports(disk: bytes) -> list[dict[str, Any]]:
"""Validate active DECB files, return SNDnnnn.TXT ASCII bytes; never mutate disk.
All active files are walked to catch crosslinks into a selected report. Unused
FAT allocations are tolerated: they can remain after an interrupted write.
"""
if len(disk) != DISK_SIZE:
raise SoundLabError(f"Expected raw 35-track DSK ({DISK_SIZE} bytes), got {len(disk)}")
fat = disk[FAT_OFFSET:FAT_OFFSET + 68]
for index, value in enumerate(fat):
if not (value < 68 or 0xC0 <= value <= 0xC9 or value == 0xFF):
raise SoundLabError(f"Invalid FAT value {value:02X} at granule {index}")
owned: dict[int, str] = {}
names: set[str] = set()
reports = []
for index in range(72):
entry = disk[DIRECTORY_OFFSET + index * 32:DIRECTORY_OFFSET + (index + 1) * 32]
if entry[0] in (0, 0xFF):
continue
try:
base = entry[:8].decode("ascii").rstrip(" ")
ext = entry[8:11].decode("ascii").rstrip(" ")
except UnicodeDecodeError as error:
raise SoundLabError(f"Non-ASCII directory name at entry {index}") from error
if not base or any(ord(c) < 33 or c in '/\\:.' for c in base + ext):
raise SoundLabError(f"Unsafe directory name at entry {index}")
name = f"{base}.{ext}" if ext else base
normalized = name.upper()
if normalized in names:
raise SoundLabError(f"Duplicate directory name: {name}")
names.add(normalized)
if entry[11] > 3 or entry[12] not in (0, 0xFF):
raise SoundLabError(f"Invalid file type/ASCII flag for {name}")
last_bytes = int.from_bytes(entry[14:16], "big")
if last_bytes > 256:
raise SoundLabError(f"Invalid final-sector byte count for {name}")
chain = []
current = entry[13]
while True:
if current >= 68:
raise SoundLabError(f"Out-of-range granule {current} for {name}")
if current in chain:
raise SoundLabError(f"FAT loop for {name}")
if current in owned:
raise SoundLabError(f"Crosslinked granule {current}: {name} and {owned[current]}")
chain.append(current)
owned[current] = name
value = fat[current]
if 0xC0 <= value <= 0xC9:
final_sectors = value - 0xC0
if final_sectors == 0 and (len(chain) != 1 or last_bytes != 0):
raise SoundLabError(f"Invalid empty final granule for {name}")
if final_sectors > 0 and last_bytes == 0:
# DOS stores 256, not zero, for a completely used last sector.
raise SoundLabError(f"Missing final-sector bytes for {name}")
break
if value == 0xFF:
raise SoundLabError(f"Allocated file {name} points to free granule {current}")
current = value
length = (len(chain) - 1) * 2304
if final_sectors:
length += (final_sectors - 1) * 256 + last_bytes
if REPORT_NAME.fullmatch(name):
if entry[12] != 0xFF:
raise SoundLabError(f"Report {name} is not marked Disk BASIC ASCII")
content = b"".join(disk[granule_offset(g):granule_offset(g) + 2304] for g in chain)[:length]
reports.append({"filename": normalized, "data": content,
"byte_count": len(content), "sha256": hashlib.sha256(content).hexdigest(),
"granules": chain, "directory_type": entry[11]})
return sorted(reports, key=lambda item: item["filename"])
def decode_note(value: str) -> str:
decoded = bytearray()
i = 0
while i < len(value):
char = value[i]
if char != "\\":
if not 32 <= ord(char) <= 126:
raise SoundLabError("Notes must use printable ASCII or escaped control bytes")
decoded.append(ord(char))
i += 1
continue
i += 1
if i >= len(value):
raise SoundLabError("Incomplete note escape")
escaped = value[i]
if escaped in "\\nrt":
decoded.append({"\\": 92, "n": 10, "r": 13, "t": 9}[escaped])
i += 1
elif escaped == "x" and i + 2 < len(value) and re.fullmatch(r"[0-9A-Fa-f]{2}", value[i + 1:i + 3]):
byte = int(value[i + 1:i + 3], 16)
if byte > 127:
raise SoundLabError("Escaped notes must remain ASCII")
decoded.append(byte)
i += 3
else:
raise SoundLabError(f"Unknown note escape at position {i}")
return decoded.decode("ascii")
def parse_tokens(line: str) -> dict[str, str]:
fields = {}
for token in line.split():
if "=" not in token:
raise SoundLabError(f"Expected KEY=VALUE token: {token}")
key, value = token.split("=", 1)
if not KEY.fullmatch(key) or not value or key in fields:
raise SoundLabError(f"Invalid or duplicate token: {token}")
fields[key] = value
if not fields:
raise SoundLabError("Empty record")
return fields
def parse_report(data: bytes, source: str = "") -> dict[str, Any]:
"""Parse evidence without turning automatic observations into listening results.
Incomplete files are useful evidence, returned with complete=False and issues.
Structural and integrity failures likewise remain visible in JSON/HTML; a
malformed header/encoding is rejected because it is not a SOUNDLAB-1 report.
"""
try:
text = data.decode("ascii")
except UnicodeDecodeError as error:
raise SoundLabError("Report is not ASCII") from error
if "\x00" in text or re.search(r"[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]", text):
raise SoundLabError("Report contains unescaped control bytes")
if "\r" in text.replace("\r\n", ""):
raise SoundLabError("Report has bare CR line endings")
lines = [line for line in text.replace("\r\n", "\n").split("\n") if line.strip()]
if not lines or lines[0] != "FORMAT=SOUNDLAB-1":
raise SoundLabError("Missing supported FORMAT=SOUNDLAB-1 header")
result: dict[str, Any] = {"format": "SOUNDLAB-1", "source": source,
"source_sha256": hashlib.sha256(data).hexdigest(),
"metadata": {}, "cases": [], "issues": [], "complete": False,
"integrity": {"record_count": "NOT_PROVIDED", "checksum_crc16": "NOT_PROVIDED"}}
current = None
footer = None
note_length = None
records = []
def issue(message: str) -> None:
result["issues"].append(message)
def merge(target: dict[str, str], fields: dict[str, str], number: int) -> None:
for key, value in fields.items():
if key in target:
issue(f"Line {number}: duplicate field {key}")
else:
target[key] = value
for number, line in enumerate(lines, 1):
if footer is not None:
issue(f"Line {number}: record after ENDRUN")
continue
if line.startswith("NOTE="):
records.append(line)
try:
note = decode_note(line[5:])
if current is None:
issue(f"Line {number}: NOTE outside CASE")
elif note_length is None:
issue(f"Line {number}: NOTE without NOTE_LENGTH")
else:
current["notes"].append(note)
if len(note.encode("ascii")) != note_length:
issue(f"Line {number}: NOTE_LENGTH mismatch")
except SoundLabError as error:
issue(f"Line {number}: {error}")
note_length = None
continue
if note_length is not None:
issue(f"Line {number}: NOTE_LENGTH not followed by NOTE")
note_length = None
try:
fields = parse_tokens(line)
except SoundLabError as error:
records.append(line)
issue(f"Line {number}: {error}")
continue
controls = set(fields) & {"FORMAT", "RUN", "CASE", "ENDCASE", "ENDRUN", "NOTE_LENGTH"}
if len(controls) > 1:
issue(f"Line {number}: conflicting control records")
if "FORMAT" in fields and number != 1:
issue(f"Line {number}: repeated FORMAT header")
if "RUN" in fields and (current is not None or result["cases"]):
issue(f"Line {number}: RUN header after CASE")
if "ENDRUN" in fields:
footer = fields
result["footer"] = fields
if current is not None:
issue(f"Line {number}: ENDRUN before ENDCASE")
if fields["ENDRUN"] != result["metadata"].get("RUN"):
issue(f"Line {number}: ENDRUN does not match RUN")
if fields.get("COMPLETE", "").upper() not in ("YES", "NO"):
issue(f"Line {number}: COMPLETE must be YES or NO")
continue
records.append(line)
if number == 1:
continue
if "CASE" in fields:
if current is not None:
issue(f"Line {number}: CASE before previous ENDCASE")
identifier = fields["CASE"].upper()
current = {"id": identifier, "fields": {}, "notes": [], "closed": False}
result["cases"].append(current)
merge(current["fields"], fields, number)
elif "ENDCASE" in fields:
if current is None:
issue(f"Line {number}: ENDCASE outside CASE")
else:
if fields["ENDCASE"].upper() != current["id"]:
issue(f"Line {number}: ENDCASE does not match CASE")
else:
current["closed"] = True
current = None
if len(fields) != 1:
issue(f"Line {number}: unexpected ENDCASE fields")
elif "NOTE_LENGTH" in fields:
if len(fields) != 1 or current is None:
issue(f"Line {number}: NOTE_LENGTH must be alone inside CASE")
try:
note_length = int(fields["NOTE_LENGTH"])
if note_length < 0 or note_length > 65535:
raise ValueError()
except ValueError:
note_length = None
issue(f"Line {number}: invalid NOTE_LENGTH")
else:
merge(current["fields"] if current is not None else result["metadata"], fields, number)
if note_length is not None:
issue("Truncated NOTE after NOTE_LENGTH")
if not result["metadata"].get("RUN"):
issue("Missing RUN identity")
attempts: set[tuple[str, int]] = set()
for case in result["cases"]:
try:
repeat_text = case["fields"].get("REPEAT", "0")
if not re.fullmatch(r"[0-9]+", repeat_text):
raise ValueError()
repeat = int(repeat_text)
if repeat > 65535:
raise ValueError()
case["repeat"] = repeat
identity = (case["id"], repeat)
if identity in attempts:
issue(f"CASE {case['id']}: duplicate REPEAT={repeat}")
attempts.add(identity)
except ValueError:
case["repeat"] = None
issue(f"CASE {case['id']}: invalid REPEAT")
for key, allowed in (("AUTO", AUTO), ("HUMAN", HUMAN)):
value = case["fields"].get(key)
if value is None:
# UNKNOWN is deliberate: absence is not a positive or negative observation.
case[key.lower()] = "UNKNOWN"
issue(f"CASE {case['id']}: missing {key}")
else:
case[key.lower()] = value.upper()
if value.upper() not in allowed:
issue(f"CASE {case['id']}: unknown {key} value {value}")
vector_crc = case["fields"].get("VECTOR_CRC16", "")
if not re.fullmatch(r"[0-9A-Fa-f]{4}", vector_crc):
issue(f"CASE {case['id']}: missing or invalid VECTOR_CRC16")
if not case["closed"]:
issue(f"CASE {case['id']}: missing ENDCASE")
if footer is None:
issue("Missing ENDRUN; partial run")
else:
if "RECORD_COUNT" in footer:
try:
valid_count = int(footer["RECORD_COUNT"]) == len(records)
except ValueError:
valid_count = False
result["integrity"]["record_count"] = "VERIFIED" if valid_count else "FAILED"
if not valid_count:
issue("RECORD_COUNT mismatch")
if "CHECKSUM_CRC16" in footer:
canonical = ("\r\n".join(records) + "\r\n").encode("ascii")
expected = f"{crc16(canonical):04X}"
valid_crc = footer["CHECKSUM_CRC16"].upper() == expected
result["integrity"]["checksum_crc16"] = "VERIFIED" if valid_crc else "FAILED"
if not valid_crc:
issue(f"CHECKSUM_CRC16 mismatch (calculated {expected})")
if footer.get("COMPLETE", "").upper() != "YES":
issue("Run marked incomplete")
result["record_count"] = len(records)
result["complete"] = footer is not None and footer.get("COMPLETE", "").upper() == "YES" and not result["issues"]
result["valid"] = not result["issues"]
return result
def validate_manifest(report: dict[str, Any], manifest: dict[str, Any]) -> list[str]:
"""Return exact identity failures; a manifest is evidence, not a trust signature."""
if not isinstance(manifest, dict):
raise SoundLabError("Manifest must be a JSON object")
problems = []
metadata = report["metadata"]
def crc_text(value: Any) -> str:
if isinstance(value, int):
return f"{value:04X}"
return str(value).upper().removeprefix("0X")
for key in ("BUILD_ID", "VECTOR_SET_CRC16"):
expected = manifest.get(key.lower(), manifest.get(key))
expected_text = crc_text(expected) if key.endswith("CRC16") else str(expected).upper()
if expected is None or expected_text != metadata.get(key, "").upper():
problems.append(f"{key} differs from manifest or is absent")
vectors = manifest.get("vectors", {})
if isinstance(vectors, list):
if not all(isinstance(item, dict) for item in vectors):
raise SoundLabError("Manifest vectors must be objects")
vectors = {item.get("id", item.get("case_id", "")): item.get("crc16", item.get("vector_crc16", "")) for item in vectors}
if not isinstance(vectors, dict):
raise SoundLabError("Manifest vectors must be a list or object")
vectors = {str(key).upper(): crc_text(value) for key, value in vectors.items()}
for case in report["cases"]:
expected = vectors.get(case["id"])
if expected is None or expected != case["fields"].get("VECTOR_CRC16", "").upper():
problems.append(f"CASE {case['id']}: vector differs from manifest or is absent")
return problems
def compare_reports(left: dict[str, Any], right: dict[str, Any], manifest: dict[str, Any] | None = None) -> dict[str, Any]:
problems = []
for key in ("BUILD_ID", "VECTOR_SET_CRC16"):
a, b = left["metadata"].get(key), right["metadata"].get(key)
if not a or not b or a.upper() != b.upper():
problems.append(f"{key} differs or is absent")
if manifest is not None:
problems.extend("Left: " + value for value in validate_manifest(left, manifest))
problems.extend("Right: " + value for value in validate_manifest(right, manifest))
if not left["valid"] or not right["valid"]:
problems.append("One or both reports are partial or invalid; outcomes are provisional")
by_id = [{(case["id"], case["repeat"]): case for case in report["cases"]} for report in (left, right)]
rows = []
for identity in sorted(set(by_id[0]) | set(by_id[1]), key=lambda item: (item[0], -1 if item[1] is None else item[1])):
identifier, repeat = identity
a, b = by_id[0].get(identity), by_id[1].get(identity)
reason = list(problems)
if a is None or b is None:
reason.append("CASE missing from one report")
elif a["fields"].get("VECTOR_CRC16", "").upper() != b["fields"].get("VECTOR_CRC16", "").upper():
reason.append("VECTOR_CRC16 differs")
row = {"case": identifier, "repeat": repeat, "left_auto": a["auto"] if a else "UNKNOWN",
"right_auto": b["auto"] if b else "UNKNOWN", "left_human": a["human"] if a else "UNKNOWN",
"right_human": b["human"] if b else "UNKNOWN", "reasons": reason}
changes = {}
if a is not None and b is not None:
for key in sorted(set(a["fields"]) | set(b["fields"])):
if key in ("CASE", "REPEAT", "VECTOR_CRC16", "AUTO", "HUMAN"):
continue
av, bv = a["fields"].get(key), b["fields"].get(key)
if av != bv:
changes[key] = {"left": av, "right": bv}
if a["notes"] != b["notes"]:
changes["NOTES"] = {"left": a["notes"], "right": b["notes"]}
row["recorded_differences"] = changes
outcomes_equal = row["left_auto"] == row["right_auto"] and row["left_human"] == row["right_human"]
row["comparison"] = "NOT_COMPARABLE" if reason else ("SAME" if outcomes_equal and not changes else "DIFFERENT")
rows.append(row)
return {"left": left["source"], "right": right["source"], "identity_issues": problems,
"manifest_checked": manifest is not None, "identity_basis": "MANIFEST" if manifest is not None else "REPORT_CLAIMS_ONLY", "cases": rows,
"notice": "Matching automatic observations do not establish audible equivalence. HUMAN is independent."}
def render_html(document: dict[str, Any]) -> str:
esc = lambda value: html.escape(str(value))
comparison = "left" in document
title = "Sound Lab comparison" if comparison else "Sound Lab report"
pieces = [f'<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>{title}</title>',
'<style>body{font:16px system-ui;max-width:75rem;margin:2rem auto;padding:0 1rem;line-height:1.5;color:#20252b;background:#fff}table{border-collapse:collapse;width:100%}td,th{padding:.5rem;border:1px solid #999;text-align:left;vertical-align:top}pre{white-space:pre-wrap;overflow-wrap:anywhere}.warning{background:#fff0c2;padding:1rem}code{overflow-wrap:anywhere}</style>', f'<h1>{title}</h1>', '<p>Automatic observations and human listening results are separate evidence. Unknown means unreported; it never means heard.</p>']
issues = document.get("identity_issues", document.get("issues", []))
if issues:
pieces.append('<div class="warning"><strong>Incomplete or unverified evidence</strong><ul>' + ''.join(f'<li>{esc(value)}</li>' for value in issues) + '</ul></div>')
if comparison:
keys = ["case", "repeat", "left_auto", "right_auto", "left_human", "right_human", "comparison", "recorded_differences", "reasons"]
rows = document["cases"]
else:
pieces.append(f'<p>Source: <code>{esc(document["source"])}</code><br>SHA-256: <code>{esc(document["source_sha256"])}</code><br>Complete: {esc(document["complete"])}</p>')
pieces.append('<h2>Run metadata and integrity</h2><pre>' + esc(json.dumps({"metadata": document["metadata"], "integrity": document["integrity"]}, indent=2)) + '</pre>')
keys = ["case", "repeat", "auto", "human", "closed", "notes", "recorded_fields"]
rows = [{"case": case["id"], "repeat": case["repeat"], "auto": case["auto"], "human": case["human"], "closed": case["closed"], "notes": "\n".join(case["notes"]), "recorded_fields": json.dumps(case["fields"], sort_keys=True)} for case in document["cases"]]
pieces.append('<h2>Cases</h2><table><thead><tr>' + ''.join(f'<th scope="col">{esc(key)}</th>' for key in keys) + '</tr></thead><tbody>')
for row in rows:
pieces.append('<tr>' + ''.join(f'<td><pre>{esc(row.get(key, ""))}</pre></td>' for key in keys) + '</tr>')
pieces.append('</tbody></table></html>')
return '\n'.join(pieces)
def render_csv(document: dict[str, Any]) -> str:
stream = io.StringIO(newline="")
if "left" in document:
fields = ["case", "repeat", "left_auto", "right_auto", "left_human", "right_human", "comparison", "recorded_differences", "reasons"]
rows = document["cases"]
else:
# Union preserves timing/status fields, rather than reducing reports to outcomes.
extra = sorted({key for case in document["cases"] for key in case["fields"]} - {"CASE", "REPEAT", "AUTO", "HUMAN"})
fields = ["case", "repeat", "auto", "human", "closed", "notes"] + extra
rows = [{"case": case["id"], "repeat": case["repeat"], "auto": case["auto"], "human": case["human"], "closed": case["closed"], "notes": '\n'.join(case["notes"]), **{key: case["fields"].get(key, "") for key in extra}} for case in document["cases"]]
writer = csv.DictWriter(stream, fieldnames=fields)
writer.writeheader()
writer.writerows(rows)
return stream.getvalue()
def write_outputs(outputs: dict[Path, bytes], overwrite: bool = False) -> None:
"""Preflight every target before any writes; originals are never implicitly replaced."""
for path in outputs:
if path.is_symlink() or (path.exists() and (not overwrite or not path.is_file())):
raise SoundLabError(f"Refusing to replace {path}; select a fresh folder or use --overwrite for regular files")
for path, data in outputs.items():
path.parent.mkdir(parents=True, exist_ok=True)
with path.open("wb" if overwrite else "xb") as handle:
handle.write(data)
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
sub = parser.add_subparsers(dest="operation", required=True)
for operation in ("extract", "convert", "compare"):
command = sub.add_parser(operation)
command.add_argument("source", type=Path)
if operation == "compare":
command.add_argument("other", type=Path)
command.add_argument("--output", required=True, type=Path)
command.add_argument("--overwrite", action="store_true")
if operation != "extract":
command.add_argument("--manifest", type=Path, help="Authoritative build/vector JSON manifest")
args = parser.parse_args(argv)
try:
outputs = {}
if args.operation == "extract":
disk = args.source.read_bytes()
reports = extract_reports(disk)
if not reports:
raise SoundLabError("No SNDnnnn.TXT ASCII reports found")
receipt = {"disk": args.source.name, "disk_byte_count": len(disk), "disk_sha256": hashlib.sha256(disk).hexdigest(), "reports": []}
for report in reports:
outputs[args.output / report["filename"]] = report["data"]
receipt["reports"].append({key: value for key, value in report.items() if key != "data"})
outputs[args.output / "extraction.json"] = (json.dumps(receipt, indent=2) + '\n').encode()
else:
left = parse_report(args.source.read_bytes(), args.source.name)
manifest = json.loads(args.manifest.read_text()) if args.manifest else None
if args.manifest and not isinstance(manifest, dict):
raise SoundLabError("Manifest must be a JSON object")
if args.operation == "compare":
document = compare_reports(left, parse_report(args.other.read_bytes(), args.other.name), manifest)
stem = "comparison"
else:
document = left
if manifest is not None:
document["manifest_issues"] = validate_manifest(document, manifest)
document["issues"].extend(document["manifest_issues"])
document["valid"] = document["valid"] and not document["manifest_issues"]
document["complete"] = document["complete"] and document["valid"]
stem = args.source.stem
outputs = {args.output / f"{stem}.json": (json.dumps(document, indent=2) + '\n').encode(), args.output / f"{stem}.csv": render_csv(document).encode(), args.output / f"{stem}.html": render_html(document).encode()}
# Never allow an output to alias any supplied source, even with --overwrite.
sources = [args.source] + ([args.other] if args.operation == "compare" else [])
if getattr(args, "manifest", None):
sources.append(args.manifest)
source_paths = {path.resolve() for path in sources}
if any(path.resolve() in source_paths or any(path.exists() and path.samefile(source) for source in sources) for path in outputs):
raise SoundLabError("Output would replace an input; choose another folder")
write_outputs(outputs, args.overwrite)
print(f"Wrote {len(outputs)} files to {args.output}")
if args.operation != "extract" and (document.get("issues") or document.get("identity_issues") or any(row.get("comparison") == "NOT_COMPARABLE" for row in document["cases"])):
print("Warning: evidence is incomplete, invalid, or not comparable; inspect JSON/HTML", file=sys.stderr)
return 2
return 0
except (OSError, SoundLabError, json.JSONDecodeError) as error:
print(f"soundlab: {error}", file=sys.stderr)
return 1
if __name__ == "__main__":
raise SystemExit(main())
+122
View File
@@ -0,0 +1,122 @@
// SPDX-License-Identifier: GPL-3.0-or-later
// Isolated headless test: real Disk BASIC/FD502 path, private local ROM inputs.
#include "../../../tests/toolchain/ssc/session.h"
static void type(Session& run, const std::string& text) {
for(char c:text) {
if(c>='A' && c<='Z') run.press(c-'@');
else if(c>='0' && c<='9') run.press(32+c-'0');
else if(c=='-') run.press(45);
else if(c=='"') run.press(34,true);
else if(c=='\r') run.press(48);
else throw std::runtime_error("Unsupported input character");
}
}
static void capture(Session& run,const fs::path& path) {
for(unsigned i=0;i<3;++i) run.tick();
auto frame=run.machine.snapshot().frame;
require(frame && frame->pixels.size()==Frame::width*Frame::height,"No guest raster");
std::ofstream file(path,std::ios::binary);
file<<"P6\n"<<Frame::width<<' '<<Frame::height<<"\n255\n";
for(auto pixel:frame->pixels) { file.put(char(pixel>>16));file.put(char(pixel>>8));file.put(char(pixel)); }
}
static void select(Session& run,const std::string& id) {
type(run,"4"); run.until("CASE ID"); type(run,id+"\r");
run.until("ENTER TO PLAY",2400); type(run,"\r"); run.until("H HEARD",2400);
}
struct NeverReady final:CartridgeDevice {
unsigned reads=0,writes=0;
void reset() override {}
void horizontalSync(DeviceHost&) override {}
std::uint8_t readMemory(std::uint16_t)const override{return 0;}
std::uint8_t readPort(std::uint8_t p,DeviceHost&)override {if(p==0x7e){++reads;return 1;}return 0;}
void writePort(std::uint8_t p,std::uint8_t,DeviceHost&)override {if(p==0x7e)++writes;}
};
static void writeFile(const fs::path& path,const Bytes& bytes) {
std::ofstream file(path,std::ios::binary);
file.write(reinterpret_cast<const char*>(bytes.data()),bytes.size());
require(bool(file),"Cannot write owned test output");
}
int main(int argc,char**argv) {
try {
require(argc==4,"Usage: run ROM_DIRECTORY SOUNDLAB.DSK OUTPUT_DIRECTORY");
fs::path roms=argv[1], out=argv[3]; fs::create_directories(out);
auto system=readFile(roms/"coco3.rom"), diskrom=readFile(roms/"disk11.rom");
auto chips=readFile(roms/"pic-7040-510.bin"), speech=readFile(roms/"sp0256-al2.bin");
chips.insert(chips.end(),speech.begin(),speech.end());
for(auto cpu:{Processor::MC6809,Processor::HD6309}) {
std::string label=cpu==Processor::MC6809?"6809":"6309";
Session run(cpu,system,diskrom,std::make_shared<SpeechSoundDevice>(chips));
run.floppy->mount(0,DiskImage::load(readFile(argv[2])));
type(run,"DOS\r"); run.until("WELCOME, LISTENER",1200);
type(run,"11ND"); run.until("MAIN MENU",2400);
if(cpu==Processor::MC6809) { run.until("REPORT SAVED",2400); capture(run,out/"main-menu.ppm"); }
run.audio.clear();
type(run,"1"); run.until("ENTER TO PLAY",2400); type(run,"\r"); run.until("H HEARD",2400);
run.checkSignal(0); // PCM signal only; never a listening verdict.
type(run,"R"); run.until("ENTER TO PLAY",2400); type(run,"\r"); run.until("ATTEMPT 1",2400); run.until("H HEARD",2400);
type(run,"U"); run.until("ENTER TO PLAY",2400); type(run,"\r"); run.until("H HEARD",2400);
type(run,"X"); run.until("MAIN MENU",2400);
type(run,"Q"); run.until("SOUND LAB FINISHED",2400);
for(unsigned i=0;i<30;++i) run.tick();
require(run.contains("OK"),"Did not return to BASIC");
require(run.floppy->writeEvents(0)>0,"No report disk writes");
writeFile(out/(label+"-reports.dsk"),run.floppy->image(0)->bytes());
saveWav(out/(label+"-showcase.wav"),run.audio);
std::ofstream(out/(label+"-final.txt"))<<run.machine.copyScreenText();
std::cout<<"PASS "<<label<<" actual DOS boot, speech PCM, repeat, uncertain/abort, reports, BASIC return\n";
}
// No physical-presence inference: absent hardware still permits menu/quit.
{
Session absent(Processor::MC6809,system,diskrom,nullptr);
absent.floppy->mount(0,DiskImage::load(readFile(argv[2]),true));
type(absent,"RUN\"SOUNDLAB\"\r"); absent.until("WELCOME, LISTENER",1200);
type(absent,"11NM"); absent.until("MAIN MENU");
type(absent,"1"); absent.until("ENTER TO PLAY"); type(absent,"\r"); absent.until("H HEARD",3000);
type(absent,"X"); absent.until("MAIN MENU"); type(absent,"Q"); absent.until("SOUND LAB FINISHED");
require(absent.floppy->writeEvents(0)==0,"Screen-only run wrote disk");
std::cout<<"PASS absent SSC bounded observation and screen-only return without writes\n";
}
{
Session engineering(Processor::MC6809,system,diskrom,std::make_shared<SpeechSoundDevice>(chips));
engineering.floppy->mount(0,DiskImage::load(readFile(out/"6809-reports.dsk")));
type(engineering,"DOS\r"); engineering.until("WELCOME, LISTENER",1200);
type(engineering,"11ND"); engineering.until("MAIN MENU",2400);
engineering.until("REPORT SAVED",2400);
require(!engineering.contains("SND0001.TXT"),"Existing report filename was reused on relaunch");
for(const auto&id:{"REG01","REG02","NOI01","ENV01-10","ALP01-00"}) {
auto first=engineering.audio.size();
select(engineering,id);
if(std::string(id)!="ALP01-00") engineering.checkSignal(first);
if(std::string(id)=="REG01") capture(engineering,out/"direct-register-result.ppm");
type(engineering,"X"); engineering.until("MAIN MENU",2400);
}
type(engineering,"Q"); engineering.until("SOUND LAB FINISHED",2400);
for(unsigned i=0;i<30;++i) engineering.tick();
writeFile(out/"engineering-reports.dsk",engineering.floppy->image(0)->bytes());
std::cout<<"PASS held AY/direct FF data, noise, envelope, silent pause, report rollover and filename preservation\n";
}
{
auto stall=std::make_shared<NeverReady>();
Session stopped(Processor::MC6809,system,diskrom,nullptr,false,stall);
stopped.floppy->mount(0,DiskImage::load(readFile(argv[2]),true));
type(stopped,"DOS\r"); stopped.until("WELCOME, LISTENER",1200);
type(stopped,"11NM"); stopped.until("MAIN MENU");
type(stopped,"1"); stopped.until("ENTER TO PLAY"); type(stopped,"\r"); stopped.until("TIMEOUT / RESET",1200);
require(stall->reads>1 && stall->writes==0,"Bounded ready polling wrote to a not-ready device");
type(stopped,"X"); stopped.until("MAIN MENU"); type(stopped,"Q"); stopped.until("SOUND LAB FINISHED");
std::cout<<"PASS never-ready bounded timeout with zero command writes\n";
}
{
Session panic(Processor::MC6809,system,diskrom,std::make_shared<SpeechSoundDevice>(chips));
panic.floppy->mount(0,DiskImage::load(readFile(argv[2]),true));
type(panic,"DOS\r"); panic.until("WELCOME, LISTENER",1200);
type(panic,"11NM"); panic.until("MAIN MENU"); type(panic,"1"); panic.until("ENTER TO PLAY"); type(panic,"\r"); panic.until("PLAYING");
type(panic,"X"); panic.until("ABORTED",1200); panic.until("H HEARD");
type(panic,"X"); panic.until("MAIN MENU"); type(panic,"Q"); panic.until("SOUND LAB FINISHED");
require(panic.floppy->writeEvents(0)==0,"Panic screen-only path wrote disk");
std::cout<<"PASS panic during playback and safe return\n";
}
return 0;
} catch(const std::exception&e) { std::cerr<<e.what()<<'\n'; return 1; }
}
+169
View File
@@ -0,0 +1,169 @@
# SPDX-License-Identifier: GPL-3.0-or-later
"""Authored PCM fixtures; no ROMs, hardware, dependencies or listening claims."""
import hashlib
import importlib.util
import json
import math
from pathlib import Path
import struct
import subprocess
import sys
import tempfile
import unittest
import wave
SCRIPT = Path(__file__).resolve().parents[1] / "audio" / "analyze.py"
SPEC = importlib.util.spec_from_file_location("sound_lab_audio", SCRIPT)
audio = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(audio)
class AudioTests(unittest.TestCase):
def setUp(self):
self.temporary = tempfile.TemporaryDirectory(prefix="soundlab-audio-")
self.addCleanup(self.temporary.cleanup)
self.directory = Path(self.temporary.name)
def wav(self, channels, rate=48000, width=2):
path = self.directory / "capture.wav"
payload = bytearray()
for frame in zip(*channels):
for value in frame:
payload.extend((value + 128 if width == 1 else value).to_bytes(width, "little", signed=width != 1))
with wave.open(str(path), "wb") as output:
output.setnchannels(len(channels))
output.setsampwidth(width)
output.setframerate(rate)
output.writeframes(payload)
return path
def manifest(self, duration=1, **kwargs):
segment = dict(case_id="AUTHORED", kind="tone", start_seconds=0, end_seconds=duration)
segment.update(kwargs)
path = self.directory / "intervals.json"
path.write_text(json.dumps({"segments": [segment]}))
return path
def sine(self, rate, hz, amplitude=16384):
return [round(amplitude * math.sin(2 * math.pi * hz * index / rate)) for index in range(rate)]
def test_tone_both_sample_rates_and_input_hashes(self):
for rate in (44100, 48000):
with self.subTest(rate=rate):
wav = self.wav([self.sine(rate, 440)], rate)
manifest = self.manifest(nominal_hz=440)
original = wav.read_bytes()
report = audio.analyze(wav, manifest)
channel = report["segments"][0]["channels"][0]
self.assertEqual(report["capture"]["sample_rate_hz"], rate)
self.assertAlmostEqual(channel["frequency"]["estimated_hz"], 440, delta=0.02)
self.assertAlmostEqual(channel["rms_full_scale"], 0.5 / math.sqrt(2), delta=0.0001)
self.assertEqual(report["capture"]["sha256"], hashlib.sha256(original).hexdigest())
self.assertEqual(wav.read_bytes(), original)
self.assertEqual(report["human_status"], "NOT_OBSERVED")
self.assertEqual(channel["assessment"], "MEASURE_BASELINE")
def test_silence_and_rails(self):
wav = self.wav([[0] * 48000])
report = audio.analyze(wav, self.manifest(kind="silence"))
channel = report["segments"][0]["channels"][0]
self.assertEqual(channel["rms_full_scale"], 0)
self.assertEqual(channel["near_zero_ratio"], 1)
self.assertNotIn("frequency", channel)
wav = self.wav([[-32768, 32767, 0, 1]])
channel = audio.analyze(wav, self.manifest(duration=4 / 48000, kind="noise"))["segments"][0]["channels"][0]
self.assertEqual(channel["clipping_count"], 2)
self.assertEqual(channel["peak_full_scale"], 1)
self.assertEqual(channel["near_zero_ratio"], 0.5)
def test_stereo_keeps_different_channels(self):
wav = self.wav([self.sine(48000, 440), self.sine(48000, 880, 8192)])
channels = audio.analyze(wav, self.manifest())["segments"][0]["channels"]
self.assertAlmostEqual(channels[0]["frequency"]["estimated_hz"], 440, delta=0.02)
self.assertAlmostEqual(channels[1]["frequency"]["estimated_hz"], 880, delta=0.02)
self.assertAlmostEqual(channels[0]["rms_full_scale"] / channels[1]["rms_full_scale"], 2, delta=0.001)
def test_supported_integer_widths(self):
for width in (1, 2, 3, 4):
with self.subTest(width=width):
wav = self.wav([[0, 1, -1, 2]], width=width)
report = audio.analyze(wav, self.manifest(duration=4 / 48000, kind="silence"))
self.assertEqual(report["capture"]["bit_depth"], width * 8)
self.assertEqual(report["segments"][0]["channels"][0]["near_zero_ratio"], 0.75)
def test_interval_validation_and_rounding(self):
wav = self.wav([[0] * 48000])
for kwargs in ({"start_seconds": -1}, {"end_seconds": 2}, {"end_seconds": 0},
{"start_seconds": 0.5, "end_seconds": 0.4}, {"start_seconds": float("nan")},
{"kind": "unknown"}, {"end_seconds": True}, {"case_id": ""},
{"start_seconds": 0.000001, "end_seconds": 0.000002}):
with self.subTest(kwargs=kwargs):
with self.assertRaises(ValueError):
audio.analyze(wav, self.manifest(**kwargs))
report = audio.analyze(wav, self.manifest(start_seconds=0.00001, end_seconds=0.00005))
self.assertEqual(report["segments"][0]["start_frame"], 1)
self.assertEqual(report["segments"][0]["stop_frame"], 3)
self.assertEqual(report["segments"][0]["byte_offset_in_pcm_payload"], 2)
def test_compression_float_width_and_truncation_rejected(self):
wav = self.wav([[0] * 48])
original = wav.read_bytes()
for format_tag, bits, block_align in ((6, 16, 2), (3, 32, 4), (1, 40, 5)):
with self.subTest(format_tag=format_tag, bits=bits):
damaged = bytearray(original)
struct.pack_into("<H", damaged, 20, format_tag)
struct.pack_into("<H", damaged, 34, bits)
struct.pack_into("<H", damaged, 32, block_align)
wav.write_bytes(damaged)
with self.assertRaises(ValueError):
audio.load_pcm(wav)
wav.write_bytes(original[:-5])
with self.assertRaises(ValueError):
audio.load_pcm(wav)
def test_explicit_tolerance_and_no_inferred_listening(self):
wav = self.wav([self.sine(48000, 440)])
tolerance = {"absolute_hz": 1, "qualification": "Authored digital fixture; known sample rate"}
report = audio.analyze(wav, self.manifest(nominal_hz=440, frequency_tolerance=tolerance))
self.assertEqual(report["segments"][0]["channels"][0]["assessment"], "WITHIN_QUALIFIED_TOLERANCE")
report = audio.analyze(wav, self.manifest(nominal_hz=450, frequency_tolerance=tolerance))
self.assertEqual(report["segments"][0]["channels"][0]["assessment"], "OUTSIDE_QUALIFIED_TOLERANCE")
self.assertEqual(report["assessment"], "MEASURE_BASELINE")
with self.assertRaises(ValueError):
audio.analyze(wav, self.manifest(nominal_hz=440, frequency_tolerance={"absolute_hz": 1}))
wav = self.wav([[0] * 48000])
channel = audio.analyze(wav, self.manifest())["segments"][0]["channels"][0]
self.assertIsNone(channel["frequency"]["estimated_hz"])
def test_repeated_comparison_requires_both_identities(self):
wav = self.wav([self.sine(48000, 440)])
manifest = self.manifest(vector_id="VECTOR-A")
first = json.loads(manifest.read_text())["segments"][0]
cases = [first, dict(first), dict(first, vector_id="VECTOR-B"),
dict(first, case_id="OTHER"), {k: v for k, v in first.items() if k != "vector_id"}]
manifest.write_text(json.dumps(cases))
comparisons = audio.analyze(wav, manifest)["repeated_cases"]
self.assertEqual(len(comparisons), 1)
self.assertEqual(comparisons[0]["observed_segment_index"], 1)
self.assertEqual(comparisons[0]["assessment"], "OBSERVED")
def test_cli_protects_existing_reports_and_inputs(self):
wav = self.wav([[0] * 48])
manifest = self.manifest(duration=0.001)
output = self.directory / "report.json"
command = [sys.executable, str(SCRIPT), str(wav), str(manifest), "--output", str(output)]
result = subprocess.run(command, capture_output=True)
self.assertEqual(result.returncode, 0, result.stderr)
original_report = output.read_bytes()
self.assertEqual(subprocess.run(command, capture_output=True).returncode, 2)
self.assertEqual(output.read_bytes(), original_report)
self.assertEqual(subprocess.run(command + ["--overwrite"], capture_output=True).returncode, 0)
original = wav.read_bytes()
self.assertEqual(subprocess.run(command[:-1] + [str(wav), "--overwrite"], capture_output=True).returncode, 2)
self.assertEqual(wav.read_bytes(), original)
if __name__ == "__main__":
unittest.main()
@@ -0,0 +1,113 @@
# SPDX-License-Identifier: GPL-3.0-or-later
"""Authored integration fixtures for post-native Sound Lab report qualification."""
import contextlib
import importlib.util
import io
import json
from pathlib import Path
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
def load(name, path):
spec = importlib.util.spec_from_file_location(name, path)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
fixture = load('soundlab_report_fixtures', ROOT / 'tests' / 'test_reports.py')
verify = load('soundlab_verify_reports', ROOT / 'verify_reports.py')
def run_text(number=1, human='UNSURE'):
text = fixture.make_report(human='NOT_OBSERVED', ending=False).decode('ascii')
header, body = text.split('CASE=', 1)
header = header.replace('RUN=0001', f'RUN={number:04d}')
case0 = 'CASE=' + body.replace('ENDCASE=', 'REPEAT=0\r\nNOTE_LENGTH=0\r\nNOTE=\r\nENDCASE=')
case1 = case0.replace('REPEAT=0', 'REPEAT=1').replace('HUMAN=NOT_OBSERVED', 'HUMAN=' + human)
text = header + case0 + case1
raw = text.encode('ascii')
footer = f'ENDRUN={number:04d} COMPLETE=YES RECORD_COUNT={len(text.splitlines())} CHECKSUM_CRC16={verify.reports.crc16(raw):04X}\r\n'
return raw + footer.encode('ascii')
def setup_build(root, *, bad_human=False, changed_binary=False, retained_changed=False):
(root / 'qualification').mkdir()
binary = b'Authored loader fixture; not executable.'
basic_source = b'10 PRINT "FIXTURE"\n'
basic_disk = b'\r' + basic_source.replace(b'\n', b'\r')
pristine = [('SOUNDLAB.BIN', binary, [0]), ('SOUNDLAB.BAS', basic_disk, [1])]
(root / 'SOUNDLAB.BIN').write_bytes(binary)
(root / 'SOUNDLAB.BAS').write_bytes(basic_source)
(root / 'SOUNDLAB.DSK').write_bytes(fixture.make_disk(pristine))
manifest = {'build_id': 'TEST-1', 'vector_set_crc16': '1234', 'vectors': [{'case_id': 'TON01-A', 'crc16': '7ABC'}], 'artifacts': []}
for name in ('SOUNDLAB.BIN', 'SOUNDLAB.BAS', 'SOUNDLAB.DSK'):
data = (root / name).read_bytes()
manifest['artifacts'].append({'filename': name, 'bytes': len(data), 'sha256': verify.sha256(data)})
(root / 'SOUNDLAB-manifest.json').write_text(json.dumps(manifest))
for label in ('6809', '6309', 'engineering'):
files = list(pristine)
if changed_binary and label == '6309':
files[0] = ('SOUNDLAB.BIN', b'Changed fixture', [0])
text = run_text(human='HEARD' if bad_human and label == '6309' else 'UNSURE')
if retained_changed and label == 'engineering':
text = text.replace(b'HUMAN=UNSURE', b'HUMAN=NO_SOUND')
# Restore valid footer so preservation is independently tested.
text = text.split(b'ENDRUN=')[0]
text += f'ENDRUN=0001 COMPLETE=YES RECORD_COUNT={len(text.splitlines())} CHECKSUM_CRC16={verify.reports.crc16(text):04X}\r\n'.encode()
files.append(('SND0001.TXT', text, [2]))
if label == 'engineering':
files.append(('SND0002.TXT', run_text(2), [3]))
(root / 'qualification' / f'{label}-reports.dsk').write_bytes(fixture.make_disk(files))
class GuestContractTests(unittest.TestCase):
def test_complete_native_contract_preserves_sources(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
setup_build(root)
inputs = {path: path.read_bytes() for path in root.rglob('*') if path.is_file()}
result = verify.qualify(root)
self.assertTrue(result['passed'])
self.assertTrue(result['engineering_original_reports_byte_identical'])
self.assertEqual(result['engineering_new_reports'], ['SND0002.TXT'])
self.assertTrue(all(run['repeat_observed'] and run['unsure_recorded'] for run in result['runs'].values()))
self.assertEqual(inputs, {path: path.read_bytes() for path in inputs})
def test_native_contract_rejects_fabricated_heard(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
setup_build(root, bad_human=True)
with self.assertRaisesRegex(verify.reports.SoundLabError, 'fabricate HUMAN=HEARD'):
verify.qualify(root)
def test_native_contract_rejects_changed_binary(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
setup_build(root, changed_binary=True)
with self.assertRaisesRegex(verify.reports.SoundLabError, 'SOUNDLAB.BIN missing or changed'):
verify.qualify(root)
def test_native_contract_rejects_changed_retained_report(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
setup_build(root, retained_changed=True)
with self.assertRaisesRegex(verify.reports.SoundLabError, 'modified or removed original 6809 report'):
verify.qualify(root)
def test_optional_receipt_never_implicitly_replaces_existing_output(self):
with tempfile.TemporaryDirectory() as directory, contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
root = Path(directory)
setup_build(root)
receipt = root / 'receipt.json'
args = ['--build-dir', str(root), '--receipt', str(receipt)]
self.assertEqual(verify.main(args), 0)
self.assertEqual(verify.main(args), 1)
self.assertEqual(verify.main(args + ['--overwrite']), 0)
self.assertEqual(verify.main(['--build-dir', str(root), '--receipt', str(root / 'SOUNDLAB.DSK'), '--overwrite']), 1)
self.assertTrue(verify.qualify(root)['passed'])
if __name__ == '__main__':
unittest.main()
+358
View File
@@ -0,0 +1,358 @@
# SPDX-License-Identifier: GPL-3.0-or-later
"""Authored, ROM-free fixtures for Sound Lab report evidence and DECB extraction."""
import hashlib
import importlib.util
import json
from pathlib import Path
import tempfile
import unittest
MODULE = Path(__file__).resolve().parents[1] / "host" / "soundlab_reports.py"
spec = importlib.util.spec_from_file_location("soundlab_reports", MODULE)
reports = importlib.util.module_from_spec(spec)
spec.loader.exec_module(reports)
def make_report(*, auto="OBSERVED", human="HEARD", ending=True, case="TON01-A", crc="7ABC", build="TEST-1", vector_set="1234", note=None):
lines = ["FORMAT=SOUNDLAB-1", f"RUN=0001 TARGET=REALCOCO BUILD_ID={build} VECTOR_SET_CRC16={vector_set}",
"MACHINE=COCO3 VIDEO=NTSC SPEED=NORMAL CART=26-3144A MOD=UNKNOWN",
f"CASE={case} VECTOR_CRC16={crc} AUTO={auto} HUMAN={human}",
"TX_COUNT=11 READY_TIMEOUTS=0 TICK_UNIT=VSYNC TICK_RATE_NUM=60000 TICK_RATE_DEN=1001",
"START_TICK=1234 END_TICK=1260 POLL_RESOLUTION_US=UNKNOWN", "STATUS_BEFORE=E0 STATUS_AFTER=E0"]
if note is not None:
lines.extend([f"NOTE_LENGTH={len(reports.decode_note(note))}", "NOTE=" + note])
lines.append(f"ENDCASE={case}")
if ending:
checksum = reports.crc16(('\r\n'.join(lines) + '\r\n').encode())
lines.append(f"ENDRUN=0001 COMPLETE=YES RECORD_COUNT={len(lines)} CHECKSUM_CRC16={checksum:04X}")
return ('\r\n'.join(lines) + '\r\n').encode()
def make_disk(files):
"""files is (name, data, explicit fragmented granule chain) tuples."""
disk = bytearray([0xFF] * reports.DISK_SIZE)
for index, (name, data, chain) in enumerate(files):
if not 0 < len(data) <= 2304 * len(chain) or len(data) <= 2304 * (len(chain) - 1):
raise ValueError("Fixture chain must exactly cover nonempty data")
base, ext = name.split(".")
entry = bytearray(32)
entry[:8] = base.encode().ljust(8, b' ')
entry[8:11] = ext.encode().ljust(3, b' ')
entry[11:14] = bytes([3, 0xFF, chain[0]])
entry[14:16] = (((len(data) - 1) % 256) + 1).to_bytes(2, 'big')
start = reports.DIRECTORY_OFFSET + index * 32
disk[start:start + 32] = entry
for position, granule in enumerate(chain):
last = position == len(chain) - 1
remaining = len(data) - position * 2304
disk[reports.FAT_OFFSET + granule] = 0xC0 + ((remaining + 255) // 256) if last else chain[position + 1]
chunk = data[position * 2304:(position + 1) * 2304]
offset = reports.granule_offset(granule)
disk[offset:offset + len(chunk)] = chunk
return disk
class DiskTests(unittest.TestCase):
def test_fragmented_chain_skips_directory_track_and_preserves_original(self):
content = b'A' * 2304 + b'B' * 2304 + b'END\r\n'
disk = make_disk([('snd0001.txt', content, [33, 34, 5])])
original = bytes(disk)
selected = reports.extract_reports(disk)
self.assertEqual(selected[0]['data'], content)
self.assertEqual(selected[0]['filename'], 'SND0001.TXT')
self.assertEqual(selected[0]['granules'], [33, 34, 5])
self.assertEqual(bytes(disk), original)
self.assertEqual(selected[0]['sha256'], hashlib.sha256(content).hexdigest())
self.assertEqual(reports.granule_offset(34), 18 * 18 * 256)
def test_full_sector_and_full_granule(self):
for size in (256, 2304, 2305):
with self.subTest(size=size):
data = bytes(i % 256 for i in range(size))
disk = make_disk([('SND0001.TXT', data, [0] if size <= 2304 else [0, 67])])
self.assertEqual(reports.extract_reports(disk)[0]['data'], data)
def test_only_report_names_extracted_and_binary_reports_rejected(self):
disk = make_disk([('NOTES.TXT', b'notes', [0]), ('SND0002.TXT', b'report', [1])])
self.assertEqual([item['filename'] for item in reports.extract_reports(disk)], ['SND0002.TXT'])
disk[reports.DIRECTORY_OFFSET + 32 + 12] = 0
with self.assertRaisesRegex(reports.SoundLabError, 'not marked.*ASCII'):
reports.extract_reports(disk)
def test_wrong_size_rejected_including_truncation(self):
for size in (0, reports.DISK_SIZE - 1, reports.DISK_SIZE + 1):
with self.subTest(size=size), self.assertRaises(reports.SoundLabError):
reports.extract_reports(bytes(size))
def test_invalid_fat_value(self):
disk = make_disk([('SND0001.TXT', b'hello', [0])])
disk[reports.FAT_OFFSET] = 0xCA
with self.assertRaisesRegex(reports.SoundLabError, 'Invalid FAT'):
reports.extract_reports(disk)
def test_fat_loop(self):
disk = make_disk([('SND0001.TXT', b'hello', [0])])
disk[reports.FAT_OFFSET] = 2
disk[reports.FAT_OFFSET + 2] = 0
with self.assertRaisesRegex(reports.SoundLabError, 'loop'):
reports.extract_reports(disk)
def test_free_granule_inside_chain(self):
disk = make_disk([('SND0001.TXT', b'hello', [0])])
disk[reports.FAT_OFFSET] = 0xFF
with self.assertRaisesRegex(reports.SoundLabError, 'free granule'):
reports.extract_reports(disk)
def test_crosslinks_with_unselected_file(self):
disk = make_disk([('SND0001.TXT', b'hello', [0]), ('OTHER.DAT', b'data', [1])])
disk[reports.DIRECTORY_OFFSET + 32 + 13] = 0
with self.assertRaisesRegex(reports.SoundLabError, 'Crosslinked'):
reports.extract_reports(disk)
def test_final_sector_count_and_empty_marker(self):
for byte_count in (257, 65535):
disk = make_disk([('SND0001.TXT', b'hello', [0])])
disk[reports.DIRECTORY_OFFSET + 14:reports.DIRECTORY_OFFSET + 16] = byte_count.to_bytes(2, 'big')
with self.subTest(byte_count=byte_count), self.assertRaisesRegex(reports.SoundLabError, 'byte count'):
reports.extract_reports(disk)
disk = make_disk([('SND0001.TXT', b'hello', [0])])
disk[reports.FAT_OFFSET] = 0xC0
with self.assertRaisesRegex(reports.SoundLabError, 'empty final granule'):
reports.extract_reports(disk)
def test_duplicate_names_and_unsafe_name(self):
disk = make_disk([('SND0001.TXT', b'a', [0]), ('snd0001.txt', b'b', [1])])
with self.assertRaisesRegex(reports.SoundLabError, 'Duplicate'):
reports.extract_reports(disk)
disk = make_disk([('SND0001.TXT', b'a', [0])])
disk[reports.DIRECTORY_OFFSET] = ord('/')
with self.assertRaisesRegex(reports.SoundLabError, 'Unsafe'):
reports.extract_reports(disk)
class ReportTests(unittest.TestCase):
def test_crc_known_vector(self):
self.assertEqual(reports.crc16(b'123456789'), 0x29B1)
def test_complete_report_and_escaped_note(self):
result = reports.parse_report(make_report(note=r'LINE\nTWO\\END\x21'))
self.assertTrue(result['complete'], result['issues'])
self.assertEqual(result['cases'][0]['notes'], ['LINE\nTWO\\END!'])
self.assertEqual(result['integrity'], {'record_count': 'VERIFIED', 'checksum_crc16': 'VERIFIED'})
self.assertEqual(result['cases'][0]['fields']['POLL_RESOLUTION_US'], 'UNKNOWN')
def test_lf_and_crlf_same_canonical_checksum(self):
self.assertTrue(reports.parse_report(make_report().replace(b'\r\n', b'\n'))['complete'])
def test_partial_run_keeps_case_evidence(self):
text = make_report(ending=False).rsplit(b'ENDCASE=', 1)[0]
result = reports.parse_report(text)
self.assertFalse(result['complete'])
self.assertFalse(result['cases'][0]['closed'])
self.assertEqual(result['cases'][0]['human'], 'HEARD')
self.assertTrue(any('partial' in issue for issue in result['issues']))
def test_bad_checksum_and_count(self):
data = make_report().replace(b'TX_COUNT=11', b'TX_COUNT=12').replace(b'RECORD_COUNT=8', b'RECORD_COUNT=7')
result = reports.parse_report(data)
self.assertFalse(result['valid'])
self.assertEqual(result['integrity']['checksum_crc16'], 'FAILED')
self.assertEqual(result['integrity']['record_count'], 'FAILED')
def test_optional_integrity_fields_are_honestly_unverified(self):
data = make_report().split(b' RECORD_COUNT=')[0] + b'\r\n'
result = reports.parse_report(data)
self.assertTrue(result['complete'])
self.assertEqual(result['integrity']['checksum_crc16'], 'NOT_PROVIDED')
def test_missing_human_never_infers_heard(self):
data = make_report().replace(b' HUMAN=HEARD', b'')
result = reports.parse_report(data)
self.assertEqual(result['cases'][0]['human'], 'UNKNOWN')
self.assertFalse(result['valid'])
def test_endcase_identity_and_trailing_records(self):
data = make_report().replace(b'ENDCASE=TON01-A', b'ENDCASE=OTHER') + b'CASE=LATE\r\n'
result = reports.parse_report(data)
self.assertFalse(result['valid'])
self.assertTrue(any('ENDCASE does not match' in value for value in result['issues']))
self.assertTrue(any('after ENDRUN' in value for value in result['issues']))
def test_notes_length_and_unknown_escape(self):
for bad in (b'NOTE_LENGTH=99\r\nNOTE=OK', b'NOTE_LENGTH=2\r\nNOTE=\\q'):
data = make_report(note='OK').replace(b'NOTE_LENGTH=2\r\nNOTE=OK', bad)
result = reports.parse_report(data)
self.assertFalse(result['valid'])
self.assertTrue(any('NOTE_LENGTH mismatch' in value or 'escape' in value for value in result['issues']))
def test_incomplete_note_and_run_identity(self):
data = make_report(ending=False).replace(b'ENDCASE=TON01-A\r\n', b'NOTE_LENGTH=3\r\n')
self.assertTrue(any('Truncated NOTE' in issue for issue in reports.parse_report(data)['issues']))
result = reports.parse_report(make_report().replace(b'ENDRUN=0001', b'ENDRUN=0002'))
self.assertTrue(any('does not match RUN' in issue for issue in result['issues']))
def test_invalid_ascii_and_format(self):
for data in (b'FORMAT=SOUNDLAB-2\n', b'FORMAT=SOUNDLAB-1\rRUN=1', b'FORMAT=SOUNDLAB-1\nNOTE=\xff', b'FORMAT=SOUNDLAB-1\n\x00'):
with self.subTest(data=data), self.assertRaises(reports.SoundLabError):
reports.parse_report(data)
def test_mixed_case_outcomes_compare_separately(self):
left = reports.parse_report(make_report(auto='observed', human='heard', case='ton01-a', crc='7abc'), 'left')
right = reports.parse_report(make_report(), 'right')
result = reports.compare_reports(left, right)
self.assertEqual(result['cases'][0]['comparison'], 'SAME')
other = reports.parse_report(make_report(human='NO_SOUND'), 'other')
result = reports.compare_reports(right, other)
self.assertEqual(result['cases'][0]['left_auto'], result['cases'][0]['right_auto'])
self.assertEqual(result['cases'][0]['comparison'], 'DIFFERENT')
def test_identity_mismatch_makes_not_comparable(self):
baseline = reports.parse_report(make_report())
for changed in (make_report(crc='ABCD'), make_report(build='OTHER'), make_report(vector_set='FFFF'), make_report(case='OTHER')):
result = reports.compare_reports(baseline, reports.parse_report(changed))
self.assertTrue(all(case['comparison'] == 'NOT_COMPARABLE' for case in result['cases']))
def test_authoritative_manifest_identity(self):
report = reports.parse_report(make_report())
manifest = {'build_id': 'TEST-1', 'vector_set_crc16': '1234', 'vectors': [{'case_id': 'TON01-A', 'crc16': '7ABC'}]}
self.assertEqual(reports.validate_manifest(report, manifest), [])
manifest['vectors'][0]['crc16'] = '1234'
compared = reports.compare_reports(report, report, manifest)
self.assertEqual(compared['cases'][0]['comparison'], 'NOT_COMPARABLE')
def test_repeated_attempts_preserved_and_compared_by_repeat(self):
base = make_report(ending=False).decode('ascii')
header, body = base.split('CASE=', 1)
case0 = 'CASE=' + body.replace('ENDCASE=', 'REPEAT=0\r\nENDCASE=')
case1 = case0.replace('REPEAT=0', 'REPEAT=1').replace('HUMAN=HEARD', 'HUMAN=UNSURE')
def finish(text):
raw = text.encode('ascii')
count = len(text.splitlines())
return raw + f'ENDRUN=0001 COMPLETE=YES RECORD_COUNT={count} CHECKSUM_CRC16={reports.crc16(raw):04X}\r\n'.encode('ascii')
left = reports.parse_report(finish(header + case0 + case1))
self.assertTrue(left['valid'], left['issues'])
self.assertEqual([case['repeat'] for case in left['cases']], [0, 1])
right = reports.parse_report(finish(header + case1 + case0))
self.assertTrue(right['valid'], right['issues'])
comparison = reports.compare_reports(left, right)
self.assertEqual([row['repeat'] for row in comparison['cases']], [0, 1])
self.assertEqual([row['comparison'] for row in comparison['cases']], ['SAME', 'SAME'])
changed = reports.parse_report(finish(header + case0 + case1.replace('HUMAN=UNSURE', 'HUMAN=NO_SOUND')))
comparison = reports.compare_reports(left, changed)
self.assertEqual([row['comparison'] for row in comparison['cases']], ['SAME', 'DIFFERENT'])
self.assertIn('case,repeat,auto,human', reports.render_csv(left))
self.assertIn('<th scope="col">repeat</th>', reports.render_html(left))
duplicate = reports.parse_report(finish(header + case0 + case0))
self.assertFalse(duplicate['valid'])
self.assertTrue(any('duplicate REPEAT=0' in issue for issue in duplicate['issues']))
def test_bad_repeat_and_missing_repeat_are_honest(self):
baseline = make_report(ending=False)
for value in ('-1', '65536', 'abc'):
invalid = baseline.replace(b'ENDCASE=', f'REPEAT={value}\r\nENDCASE='.encode()) + b'ENDRUN=0001 COMPLETE=YES\r\n'
parsed = reports.parse_report(invalid)
self.assertFalse(parsed['valid'])
self.assertIsNone(parsed['cases'][0]['repeat'])
self.assertEqual(reports.parse_report(make_report())['cases'][0]['repeat'], 0)
def test_raw_metric_differences_visible_even_with_same_outcomes(self):
a = make_report()
b = a.replace(b'TX_COUNT=11', b'TX_COUNT=12').split(b' RECORD_COUNT=')[0] + b'\r\n'
# Remove optional integrity from both: this fixture isolates metrics comparison.
a = a.split(b' RECORD_COUNT=')[0] + b'\r\n'
result = reports.compare_reports(reports.parse_report(a), reports.parse_report(b))
self.assertEqual(result['cases'][0]['comparison'], 'DIFFERENT')
self.assertEqual(result['cases'][0]['recorded_differences']['TX_COUNT'], {'left': '11', 'right': '12'})
def test_manifest_crc_aliases_and_invalid_schema(self):
report = reports.parse_report(make_report())
manifest = {'build_id': 'TEST-1', 'vector_set_crc16': 0x1234, 'vectors': {'TON01-A': '0x7abc'}}
self.assertEqual(reports.validate_manifest(report, manifest), [])
for bad in ([], {'vectors': 3}, {'vectors': ['not an object']}):
with self.subTest(manifest=bad), self.assertRaises(reports.SoundLabError):
reports.validate_manifest(report, bad)
def test_repeated_header_or_conflicting_controls(self):
for changed in (make_report().replace(b'ENDCASE=TON01-A', b'FORMAT=SOUNDLAB-1\r\nENDCASE=TON01-A'),
make_report().replace(b'CASE=TON01-A VECTOR', b'CASE=TON01-A RUN=0001 VECTOR')):
self.assertFalse(reports.parse_report(changed)['valid'])
def test_html_escapes_notes_and_csv_keeps_timing(self):
result = reports.parse_report(make_report(note='<script>alert(1)</script>'))
rendered = reports.render_html(result)
self.assertNotIn('<script>', rendered)
self.assertIn('&lt;script&gt;', rendered)
csv = reports.render_csv(result)
self.assertIn('TICK_RATE_DEN', csv)
self.assertIn('1001', csv)
class CliTests(unittest.TestCase):
def test_extract_convert_and_no_overwrites(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
disk = root / 'SOUNDLAB.DSK'
disk.write_bytes(make_disk([('SND0001.TXT', make_report(), [0])]))
output = root / 'reports'
self.assertEqual(reports.main(['extract', str(disk), '--output', str(output)]), 0)
self.assertEqual((output / 'SND0001.TXT').read_bytes(), make_report())
self.assertEqual(reports.main(['extract', str(disk), '--output', str(output)]), 1)
self.assertEqual(reports.main(['convert', str(output / 'SND0001.TXT'), '--output', str(root / 'converted')]), 0)
result = json.loads((root / 'converted' / 'SND0001.json').read_text())
self.assertTrue(result['complete'])
self.assertEqual(reports.main(['compare', str(output / 'SND0001.TXT'), str(output / 'SND0001.TXT'), '--output', str(root / 'comparison')]), 0)
def test_partial_conversion_returns_warning_with_evidence(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
report = root / 'partial.txt'
report.write_bytes(make_report(ending=False))
self.assertEqual(reports.main(['convert', str(report), '--output', str(root / 'result')]), 2)
self.assertTrue((root / 'result' / 'partial.html').is_file())
def test_inputs_cannot_be_overwritten_even_explicitly(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
# A source named *.json is still parsed as text, but conversion would target it.
report = root / 'report.json'
data = make_report()
report.write_bytes(data)
self.assertEqual(reports.main(['convert', str(report), '--output', str(root), '--overwrite']), 1)
self.assertEqual(report.read_bytes(), data)
def test_hardlinked_source_cannot_be_overwritten(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
report = root / 'report.txt'
report.write_bytes(make_report())
(root / 'report.json').hardlink_to(report)
self.assertEqual(reports.main(['convert', str(report), '--output', str(root), '--overwrite']), 1)
self.assertEqual(report.read_bytes(), make_report())
def test_explicit_overwrite_and_invalid_manifest(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
report = root / 'report.txt'
report.write_bytes(make_report())
output = root / 'output'
self.assertEqual(reports.main(['convert', str(report), '--output', str(output)]), 0)
self.assertEqual(reports.main(['convert', str(report), '--output', str(output), '--overwrite']), 0)
manifest = root / 'bad.json'
for invalid in ('[]', 'null'):
manifest.write_text(invalid)
self.assertEqual(reports.main(['convert', str(report), '--output', str(root / 'bad'), '--manifest', str(manifest)]), 1)
def test_preflight_rejects_all_outputs_before_writing(self):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
(root / 'exists').write_bytes(b'old')
with self.assertRaises(reports.SoundLabError):
reports.write_outputs({root / 'new': b'new', root / 'exists': b'replace'})
self.assertFalse((root / 'new').exists())
(root / 'link').symlink_to(root / 'exists')
with self.assertRaises(reports.SoundLabError):
reports.write_outputs({root / 'link': b'replace'}, overwrite=True)
if __name__ == '__main__':
unittest.main()
+69
View File
@@ -0,0 +1,69 @@
# SPDX-License-Identifier: GPL-3.0-or-later
"""Host tests for authored packet boundaries and deterministic vector identities."""
import importlib.util
import json
from pathlib import Path
import tempfile
import unittest
SPEC = importlib.util.spec_from_file_location('sound_vectors', Path(__file__).resolve().parents[1] / 'vectors' / 'generate.py')
V = importlib.util.module_from_spec(SPEC)
SPEC.loader.exec_module(V)
class VectorTests(unittest.TestCase):
def test_ccitt_false_check_value(self):
self.assertEqual(V.crc16(b'123456789'), 0x29B1)
def test_operand_ff_is_not_a_terminator(self):
self.assertEqual(len(V.sound_events([15, 0, 255, 255, 0, 0, 255, 0, 255])), 2)
V.validate_tx([0xAF, 0, 255, 11, 255, 255])
def test_malformed_packets_are_rejected(self):
invalid = ([0x98, 15, 0, 12, 255], # FF consumed as duration, no boundary terminator
[0x98, 15, 16, 12, 0, 255], # invalid tone high nibble
[0x98, 0x8F, 0x60, 1, 255], # reserved noise bits
[0xB0, 64, 0, 255], [0xB0, 5, 255], # invalid code / lacks final pause
[0xAF, 14, 0, 255], [0xAF, 1, 16, 255],
[0xAF, 0, 255], # FF is operand; missing terminator
[0x90, 65], [0x8F], [256], [])
for tx in invalid:
with self.subTest(tx=tx), self.assertRaises(ValueError):
V.validate_tx(list(tx))
def test_slots_allophones_and_shapes_are_complete(self):
cases = {v['id']: v for v in V.authored_vectors()}
for slot in range(8):
self.assertEqual(cases[f'BUF01-SP{slot}']['tx'][0], 0x90 + slot)
self.assertEqual(cases[f'BUF02-SN{slot}']['tx'][0], 0x98 + slot)
for code in range(64):
self.assertEqual(cases[f'ALP01-{code:02d}']['tx'], [0xB0, code, 0, 255, 0xF0])
for shape in range(16):
self.assertIn(0x60 + shape, cases[f'ENV01-{shape:02d}']['tx'])
def test_reproducible_manifest_and_header(self):
with tempfile.TemporaryDirectory() as temp:
one, two = Path(temp) / 'one', Path(temp) / 'two'
a, b = V.emit(one), V.emit(two)
self.assertEqual(a, b)
for name in ('vectors.h', 'vectors.json'):
self.assertEqual((one / name).read_bytes(), (two / name).read_bytes())
manifest = json.loads((one / 'vectors.json').read_text())
for case in manifest['vectors']:
self.assertEqual(case['crc16_ccitt_false'], f"{V.crc16(case['tx']):04X}")
self.assertEqual(case['tx_hex'], bytes(case['tx']).hex(' ').upper())
def test_version_one_packet_identities(self):
manifest = V.build_manifest()
self.assertEqual(manifest['vector_set_crc16'], '62E5')
cases = {v['case_id']: v['crc16'] for v in manifest['vectors']}
self.assertEqual({key: cases[key] for key in ('TXT01', 'REG01', 'FUN01-TUNE', 'ALP01-63', 'ENV01-10')},
{'TXT01': 'DEB7', 'REG01': 'E5E2', 'FUN01-TUNE': 'AF2A',
'ALP01-63': '2BD5', 'ENV01-10': 'BB15'})
for case in manifest['vectors']:
self.assertLessEqual(len(case['title']), 26)
self.assertLessEqual(len(case['prompt']), 62)
if __name__ == '__main__':
unittest.main()
+115
View File
@@ -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.
+264
View File
@@ -0,0 +1,264 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Authored Sound Lab vectors; no emulator, ROM or third-party Python required."""
import argparse
import hashlib
import json
from pathlib import Path
ROOT = Path(__file__).resolve().parent
def crc16(data):
"""CRC-16/CCITT-FALSE: poly1021, initFFFF, refin=false, xorout0000."""
crc = 0xFFFF
for byte in data:
crc ^= byte << 8
for _ in range(8):
crc = ((crc << 1) ^ (0x1021 if crc & 0x8000 else 0)) & 0xFFFF
return crc
def sound_events(data):
"""Parse event boundaries; FF is legal inside operands, not at a boundary."""
pos = 0
events = []
while pos < len(data):
op = data[pos]
if op == 0xFF:
if pos != len(data) - 1:
raise ValueError('bytes after sound terminator')
return events
width = 4 if op & 0x60 == 0x60 or not op & 0x80 else 3
if pos + width >= len(data):
raise ValueError('incomplete sound event or missing terminator')
if width == 4 and op & 0x60 != 0x60 and data[pos + 1] > 15:
raise ValueError('tone coarse period outside 12-bit range')
if width == 3 and data[pos + 1] & 0x60:
raise ValueError('noise reserved period bits set')
events.append(data[pos:pos + width])
pos += width
raise ValueError('missing sound terminator')
def register_pairs(data):
pos = 0
while pos < len(data):
reg = data[pos]
if reg == 0xFF:
if pos != len(data) - 1:
raise ValueError('bytes after register terminator')
return
if reg > 13 or pos + 1 >= len(data):
raise ValueError('invalid or incomplete register pair')
maximum = (15 if reg in (1, 3, 5, 13) else
31 if reg in (6, 8, 9, 10) else 63 if reg == 7 else 255)
if data[pos + 1] > maximum:
raise ValueError('register value outside documented field width')
pos += 2
raise ValueError('missing register terminator')
def validate_tx(data):
"""Validate the deliberately bounded, single-slot command subset used here."""
if not data or any(type(b) is not int or not 0 <= b <= 255 for b in data):
raise ValueError('TX must contain bytes')
pos = 0
while pos < len(data):
cmd = data[pos]
pos += 1
if cmd in (0, 0xC7, 0xCF) or 0xD0 <= cmd <= 0xDF or 0xF0 <= cmd <= 0xFF:
continue
if cmd == 0x8F:
if pos == len(data):
raise ValueError('timer lacks operand')
pos += 1
continue
if 0x20 <= cmd < 0x80 or 0x90 <= cmd <= 0x97:
start = pos - 1 if cmd < 0x80 else pos
try:
end = data.index(13, start)
except ValueError:
raise ValueError('text lacks CR') from None
payload = data[start:end]
if not payload or any(not 32 <= b <= 126 for b in payload):
raise ValueError('non-printable text')
if len(payload) + 1 > 64:
raise ValueError('single text buffer exceeds 64 bytes')
pos = end + 1
continue
if 0x98 <= cmd <= 0x9F:
start = pos
while pos < len(data):
op = data[pos]
if op == 255:
pos += 1
break
pos += 4 if op & 0x60 == 0x60 or not op & 0x80 else 3
body = data[start:pos]
sound_events(body)
elif 0xB0 <= cmd <= 0xB7:
start = pos
while pos < len(data) and data[pos] != 255:
if data[pos] > 63:
raise ValueError('allophone outside AL2 range')
pos += 1
if pos == len(data) or pos == start or data[pos - 1] > 4:
raise ValueError('allophones need final pause and FF')
pos += 1
body = data[start:pos]
elif cmd == 0xAF or 0xB8 <= cmd <= 0xBF:
start = pos
while pos < len(data) and data[pos] != 255:
pos += 2
if pos == len(data):
raise ValueError('register packet lacks boundary terminator')
pos += 1
body = data[start:pos]
register_pairs(body)
else:
raise ValueError(f'unsupported command {cmd:02X}')
if cmd != 0xAF and len(body) > 64:
raise ValueError('single buffer exceeds 64 bytes')
return True
def tone(channel, period, volume=10, ticks=15):
if not 0 <= channel <= 2 or not 0 <= period <= 4095 or not 0 <= volume <= 31:
raise ValueError('invalid tone fields')
return [channel * 32 + volume, period >> 8, period & 255, ticks]
def noise(channel, period, volume=8, ticks=15):
return [0x80 + channel * 32 + volume, period, ticks]
def stored_sound(events, slot=0):
return [0x98 + slot] + events + [255, 0xD8 + slot]
def authored_vectors():
out = []
def add(identity, title, prompt, tx, wait=0x20, hold=0, group=2,
source='TANDY-SOUND', expectation='MEASURE_BASELINE'):
validate_tx(tx)
out.append(dict(id=identity, title=title, prompt=prompt, tx=tx,
wait_mask=wait, hold_ticks=hold, group=group,
source_claims=[source], expectation=expectation))
def text(s):
return list((s + ' \r').encode('ascii'))
add('TXT01', 'MEET YOUR ROBOT', 'HEAR THE GREETING?',
text('HELLO BRIAN. WELCOME TO THE SOUND LAB.'), 0x40, group=3,
source='TANDY-TEXT')
add('TXT02-READ', 'WORDS AND NUMBERS', 'WORDS CLEAR? NOTE PRONUNCIATION.',
text('READY PLAYER ONE. LEVEL TWO. SCORE ONE HUNDRED.'), 0x40,
source='TANDY-TEXT')
add('TXT03-LONG', 'SHORT THEN LONG', 'COMPARE WITH THE FIRST GREETING.',
text('THE ROBOT CAN SPEAK A LONGER SENTENCE.'), 0x40,
source='TANDY-TEXT')
for channel in range(3):
add('TON01-' + 'ABC'[channel], 'TONE ' + 'ABC'[channel],
'ONE CLEAR PITCH; THEN SILENCE.',
stored_sound(tone(channel, 254) + tone(channel, 254, 0, 0)),
group=3 if channel == 0 else 2)
add('TON04', 'RISING STEPS', 'DO THE THREE NOTES RISE?',
stored_sound(sum((tone(0, p, 10, 12) for p in (428, 339, 254)), []) + tone(0, 254, 0, 0)), group=3)
add('TON05', 'THREE VOICE CHORD', 'THREE NOTES TOGETHER, THEN OFF.',
stored_sound(tone(0, 428, 8, 0) + tone(1, 339, 8, 0) + tone(2, 285, 8, 24)
+ tone(0, 428, 0, 0) + tone(1, 339, 0, 0) + tone(2, 285, 0, 0)), group=3)
add('AMP01', 'SOFT TO LOUD', 'DO THE FOUR STEPS GET LOUDER?',
stored_sound(sum((tone(0, 254, v, 10) for v in (2, 5, 9, 13)), []) + tone(0, 254, 0, 0)))
add('NOI01', 'NOISE COLORS', 'NOISE CHANGES FROM HISS TO RUMBLE.',
stored_sound(sum((noise(0, p, 7, 12) for p in (1, 8, 31)), []) + noise(0, 31, 0, 0)), group=3)
add('NOI02', 'NOISE CONTINUE', 'TWO NOISE EVENTS; SAME VOLUME.',
stored_sound(noise(0, 8, 7, 15) + noise(0, 0x80 | 16, 0, 15) + noise(0, 16, 0, 0)), group=4)
# AF writes an audible fixed tone. Parent waits hold_ticks, sends00 and confirms silence.
add('REG01', 'DIRECT AY REGISTERS', 'STEADY TONE; PANIC MUST SILENCE.',
[0xAF, 0, 254, 1, 0, 7, 62, 8, 9, 255], 0, 40, 2, 'TANDY-REGISTERS')
add('REG02', 'FF IS REGISTER DATA', 'STEADY TONE; FF DATA IS NOT END.',
[0xAF, 0, 255, 1, 0, 7, 62, 8, 8, 255], 0, 40, 4, 'TANDY-REGISTERS')
add('CMD01', 'STOP AND CONTROL', 'NO SOUND AFTER ALL THREE STOPS.',
[0xC7, 0xCF, 0], 0x60, group=4, source='TANDY-COMMANDS', expectation='DOCUMENTED_CONTROL')
add('TIM01', 'BASE TIMER', 'RECORD DURATION; NO FIXED MS CLAIM.',
[0x8F, 16] + stored_sound(tone(0, 254, 8, 4) + tone(0, 254, 0, 0)), group=4,
source='TANDY-TIMER')
add('TIM02', 'FF IS DURATION DATA', 'LONG EVENT, THEN SILENCE.',
stored_sound(tone(0, 254, 8, 255) + tone(0, 254, 0, 0)), group=4)
add('FUN01-TUNE', 'ORIGINAL SHORT TUNE', 'HEAR A SMALL RISING AND FALLING TUNE.',
stored_sound(sum((tone(0, p, 9, 9) for p in (428, 339, 285, 254, 285, 339, 428)), [])
+ tone(0, 428, 0, 0)), group=3)
# Shared speech slots and independent sound slots; each case executes only its own slot.
for slot in range(8):
add(f'BUF01-SP{slot}', f'SPEECH SLOT {slot}', 'HEAR THE CORRECT SLOT NUMBER?',
[0x90 + slot] + text('BUFFER ' + ('ZERO','ONE','TWO','THREE','FOUR','FIVE','SIX','SEVEN')[slot])
+ [0xD0 + slot], 0x40, group=4, source='TANDY-COMMANDS')
add(f'BUF02-SN{slot}', f'SOUND SLOT {slot}', 'MATCH SLOT AND SHORT TONE.',
stored_sound(tone(0, 428 - 24 * slot, 8, 8) + tone(0, 254, 0, 0), slot),
group=4, source='TANDY-COMMANDS')
names = ('PA1 PA2 PA3 PA4 PA5 OY AY EH KK3 PP JH NN1 IH TT2 RR1 AX MM TT1 DH1 IY EY DD1 UW1 AO AA YY2 AE HH1 BB1 TH UH UW2 AW DD2 GG3 VV GG1 SH ZH RR2 FF KK2 KK1 ZZ NG LL WW XR WH YY1 CH ER1 ER2 OW DH2 SS NN2 HH2 OR AR YR GG2 EL BB2').split()
for code, name in enumerate(names):
add(f'ALP01-{code:02d}', f'ALLOPHONE {code:02d} {name}',
'PAUSE: EXPECT NO VOICE.' if code < 5 else 'RECORD WHAT YOU HEAR.',
[0xB0, code, 0, 255, 0xF0], 0x40, group=4, source='TANDY-ALLOPHONES')
for shape in range(16):
# Documented grammar: envelope-enabled tone immediately followed by envelope event.
events = tone(0, 254, 16, 0) + [0x60 | shape, 3, 0, 35] + tone(0, 254, 0, 0)
add(f'ENV01-{shape:02d}', f'ENVELOPE {shape:02X}', 'COMPARE SHAPE AND END SILENCE.',
stored_sound(events), group=2 if shape == 10 else 4, source='TANDY-ENVELOPE')
add('MIX01', 'ROBOT SPACEPORT', 'VOICE OVER AN AMBIENT TONE.',
stored_sound(tone(0, 339, 5, 0)) + text('WELCOME TO THE SPACE PORT.'),
0x40, 20, 3, 'TANDY-COMMANDS')
return out
def build_manifest():
vectors = authored_vectors()
for case in vectors:
raw = bytes(case['tx'])
case.update(case_id=case['id'], crc16=f'{crc16(raw):04X}',
tx_hex=raw.hex(' ').upper(), byte_count=len(raw),
crc16_ccitt_false=f'{crc16(raw):04X}', sha256=hashlib.sha256(raw).hexdigest())
identities = [v['id'] for v in vectors]
if len(set(identities)) != len(identities):
raise ValueError('duplicate vector ID')
body = dict(schema='vccplus.sound-lab.vectors.v1', vector_version='1.0',
vector_set_crc16=f"{crc16(bytes(b for case in vectors for b in case['tx'])):04X}",
authored=True, crc='CRC-16/CCITT-FALSE',
result_policy='HUMAN listening is never an AUTO pass; timings are MEASURE_BASELINE.',
source_catalog=json.loads((ROOT / 'sources.json').read_text()), vectors=vectors)
canonical = json.dumps(body, sort_keys=True, separators=(',', ':')).encode()
body['manifest_sha256'] = hashlib.sha256(canonical).hexdigest()
return body
def emit(output):
manifest = build_manifest()
output.mkdir(parents=True, exist_ok=True)
(output / 'vectors.json').write_text(json.dumps(manifest, indent=2) + '\n')
lines = ['/* Generated by vectors/generate.py; do not edit. */', '#ifndef SOUND_LAB_VECTORS_H',
'#define SOUND_LAB_VECTORS_H',
'typedef struct { const char *id; const char *title; const char *prompt;',
'const unsigned char *tx; unsigned length; unsigned crc16;',
'unsigned char wait_mask; unsigned char hold_ticks; unsigned char group; } SoundVector;']
for i, case in enumerate(manifest['vectors']):
lines.append('static const unsigned char sound_tx_%u[] = {%s};' %
(i, ','.join('0x%02X' % b for b in case['tx'])))
lines.append('static const SoundVector sound_vectors[] = {')
for i, case in enumerate(manifest['vectors']):
lines.append('{%s,%s,%s,sound_tx_%u,%u,0x%s,0x%02X,%u,%u},' %
(json.dumps(case['id']), json.dumps(case['title']), json.dumps(case['prompt']),
i, case['byte_count'], case['crc16_ccitt_false'], case['wait_mask'],
case['hold_ticks'], case['group']))
lines += ['};', '#define SOUND_VECTOR_COUNT %u' % len(manifest['vectors']),
'#define SOUND_VECTOR_VERSION "1.0"',
'#define SOUND_MANIFEST_SHA256 "%s"' % manifest['manifest_sha256'], '#endif', '']
(output / 'vectors.h').write_text('\n'.join(lines))
return manifest
if __name__ == '__main__':
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--output', type=Path, required=True)
args = parser.parse_args()
result = emit(args.output)
print(f"{len(result['vectors'])} vectors; manifest {result['manifest_sha256']}")
+74
View File
@@ -0,0 +1,74 @@
{
"schema": "vccplus.sound-lab.sources.v1",
"sources": [
{
"id": "TANDY-OWNER-1984",
"title": "Color Computer Speech/Sound Cartridge Owner's Manual",
"publisher": "Tandy Corporation",
"year": 1984,
"url": "https://colorcomputerarchive.com/repo/Documents/Manuals/Hardware/Speech-Sound%20Cartridge%20%28Tandy%29.pdf",
"sha256": "80aa645aa57da31121f7741d7373f21c5e5c69825f5a5eff8a86ad899055c92a",
"qualification": "Primary Tandy publication reproduced/OCR-typeset by Tim Lindner; 54-page2004 PDF retrieved2026-11-17. Page pixels24,26,28 inspected for AF/register0-13, timer8F, single slots and C7/CF controls. This is not a photographic original scan: original-paper comparison remains pending. Archive old filename404s; current alternate Manual filename is a newer57-page reproduction, retained separately and not used as the cited edition.",
"page_numbering": "Printed page =1-based PDF page in the54-page cited edition.",
"claims": [
{
"id": "TANDY-TEXT",
"pages": "9-11",
"section": "Speaking of the S/SC",
"fact": "Printable text is sent at FF7E with ready polling; CR completes input. The diagnostic appends a space to flush a final word as its explicit conservative authoring policy."
},
{
"id": "TANDY-COMMANDS",
"pages": "12-14,26-30",
"section": "Straight Talk; Appendix A",
"fact": "Eight speech slots support text or allophones; eight sound slots support events or register strings. Single-slot load and execute commands are used. 00 stops speech and sound without clearing stored buffers; C7 stops speech; CF stops sound."
},
{
"id": "TANDY-SOUND",
"pages": "15-20",
"section": "Sound Advice; Dial Tone; As Plain as the Noise",
"fact": "Tone events consume4 bytes, noise3; event-boundary FF terminates, operand FF is data. Final amplitude-zero events silence sustained output. Duration is between events, not an automatic noteoff."
},
{
"id": "TANDY-TIMER",
"pages": "18,20,23,26",
"section": "Event duration; Appendix A8F",
"fact": "8F accepts one0-255 base-time operand. Larger values increase event duration. No absolute event timing is asserted here."
},
{
"id": "TANDY-ENVELOPE",
"pages": "21-23,33-34",
"section": "The Envelope, Please; Appendix B",
"fact": "Envelope event is4 bytes: operation60+shape, coarse period, fine period, duration. All channels share one envelope generator. Envelope-enabled tone/noise is immediately followed by envelope group."
},
{
"id": "TANDY-REGISTERS",
"pages": "24-25,27,31-34",
"section": "Scaling the Sound Registers; Appendices A/B",
"fact": "AF enters direct register/value access; FF at a register boundary exits. Table and example explicitly include register0 despite the introductory prose saying1-13. Register operands may equalFF. R8-R10 bit4 envelope mode is documented in Appendix B though compact table lists only fixed0-15."
},
{
"id": "TANDY-ALLOPHONES",
"pages": "13-14,35-36",
"section": "Straight Talk; Appendix C",
"fact": "AL2 addresses0-63;0-4 are pauses. Allophone strings end with a pause then FF. Code order and mnemonic labels follow Appendix C; sound fidelity and duration remain measurements."
}
],
"retrieved_url": "https://tlindner.macmess.org/wp-content/uploads/2006/09/sscmanual.pdf",
"byte_count": 211234,
"alternate_reproduction": {
"url": "https://colorcomputerarchive.com/repo/Documents/Manuals/Hardware/Speech-Sound%20Cartridge%20Manual%20(Tandy).pdf",
"sha256": "7170a1c33164d654f2d92af8c708bc38bac14dbd53f3fa142da1cd724201f1de",
"pages": 57,
"role": "Discovery evidence only, not cited for command grammar."
}
}
],
"non_assertions": [
"No physical cartridge, FPGA, human listening or analog fidelity pass is claimed by this manifest.",
"Speech standby40 and sound idle20 are current SDK/model observation conventions, not source-qualified hardware acceptance assertions in this manifest.",
"No automatic controller or cartridge presence detection is inferred from a floating status byte.",
"The SDK's priming/retrigger workaround for cold one-shot envelopes is not substituted for documented packet grammar.",
"Single-slot sound/register payloads include the terminator within64 bytes. Allophone and text slots share storage; this is not16 independent speech buffers."
]
}
+166
View File
@@ -0,0 +1,166 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-3.0-or-later
"""Read-only post-native Sound Lab qualification checks; no emulator changes."""
from __future__ import annotations
import argparse
import hashlib
import importlib.util
import json
from pathlib import Path
import sys
from typing import Any
_MODULE = Path(__file__).resolve().parent / "host" / "soundlab_reports.py"
_SPEC = importlib.util.spec_from_file_location("soundlab_reports", _MODULE)
reports = importlib.util.module_from_spec(_SPEC)
_SPEC.loader.exec_module(reports)
def sha256(data: bytes) -> str:
return hashlib.sha256(data).hexdigest()
def disk_files(data: bytes) -> dict[str, bytes]:
"""Read all ordinary files after the host extractor validates every active chain."""
reports.extract_reports(data)
files = {}
fat = data[reports.FAT_OFFSET:reports.FAT_OFFSET + 68]
for index in range(72):
offset = reports.DIRECTORY_OFFSET + index * 32
entry = data[offset:offset + 32]
if entry[0] in (0, 0xFF):
continue
base = entry[:8].decode('ascii').rstrip(' ')
extension = entry[8:11].decode('ascii').rstrip(' ')
name = (base + ('.' + extension if extension else '')).upper()
current, chain = entry[13], []
while True:
chain.append(current)
successor = fat[current]
if successor >= 0xC0:
sectors = successor - 0xC0
break
current = successor
last_bytes = int.from_bytes(entry[14:16], 'big')
length = (len(chain) - 1) * 2304 + ((sectors - 1) * 256 + last_bytes if sectors else 0)
files[name] = b''.join(data[reports.granule_offset(g):reports.granule_offset(g) + 2304] for g in chain)[:length]
return files
def qualify(build_dir: Path) -> dict[str, Any]:
manifest_path = build_dir / 'SOUNDLAB-manifest.json'
manifest_bytes = manifest_path.read_bytes()
manifest = json.loads(manifest_bytes)
if not isinstance(manifest, dict) or not isinstance(manifest.get('artifacts'), list):
raise reports.SoundLabError('Build manifest lacks its artifact list')
artifacts = {item['filename'].upper(): item for item in manifest['artifacts']}
pristine_path = build_dir / 'SOUNDLAB.DSK'
pristine_bytes = pristine_path.read_bytes()
artifact = artifacts.get('SOUNDLAB.DSK')
if not artifact or artifact.get('sha256') != sha256(pristine_bytes) or artifact.get('bytes') != len(pristine_bytes):
raise reports.SoundLabError('Pristine SOUNDLAB.DSK does not match build manifest')
pristine = disk_files(pristine_bytes)
protected = {name: data for name, data in pristine.items() if name.endswith(('.BIN', '.BAS'))}
if not protected or 'SOUNDLAB.BIN' not in protected or 'SOUNDLAB.BAS' not in protected:
raise reports.SoundLabError('Pristine disk lacks the declared Sound Lab BIN/BAS files')
for name, data in protected.items():
if name not in artifacts:
continue
source = (build_dir / name).read_bytes()
if artifacts[name].get('sha256') != sha256(source) or artifacts[name].get('bytes') != len(source):
raise reports.SoundLabError(f'Host {name} differs from manifest artifact')
expected = source
if name.endswith('.BAS'):
# build.py uses writecocofile --newlines: a leading empty CR line,
# then every LF-terminated native source line followed by CR.
if not source.endswith(b'\n') or b'\r' in source:
raise reports.SoundLabError(f'Host {name} is not the expected LF-terminated BASIC source')
expected = b'\r' + source.replace(b'\n', b'\r')
if data != expected:
raise reports.SoundLabError(f'Pristine {name} differs from its declared build input conversion')
outcome: dict[str, Any] = {
'schema': 'vccplus.sound-lab.native-report-qualification.v1',
'build_id': manifest.get('build_id'), 'vector_set_crc16': manifest.get('vector_set_crc16'),
'manifest_sha256': sha256(manifest_bytes), 'pristine_disk_sha256': sha256(pristine_bytes),
'protected_files': {name: {'bytes': len(data), 'sha256': sha256(data)} for name, data in sorted(protected.items())},
'runs': {},
'evidence_limits': ['Native emulator checks only; no real-cartridge, FPGA or listening acceptance.',
'HUMAN=UNSURE and NOT_OBSERVED are automation input choices, not a listening verdict.',
'All source disks were read-only host inputs; no source files were modified.']}
extracted: dict[str, dict[str, bytes]] = {}
for label in ('6809', '6309', 'engineering'):
path = build_dir / 'qualification' / (label + '-reports.dsk')
raw = path.read_bytes()
contents = disk_files(raw)
for name, expected in protected.items():
if contents.get(name) != expected:
raise reports.SoundLabError(f'{label}: pristine {name} missing or changed')
selected = reports.extract_reports(raw)
if not selected:
raise reports.SoundLabError(f'{label}: no native report files')
extracted[label] = {item['filename']: item['data'] for item in selected}
run_result = {'disk_sha256': sha256(raw), 'protected_files_unchanged': True, 'reports': [],
'repeat_observed': False, 'unsure_recorded': False, 'human_heard_fabricated': False}
for item in selected:
name = item['filename']
parsed = reports.parse_report(item['data'], name)
identity_issues = reports.validate_manifest(parsed, manifest)
if not parsed['complete'] or not parsed['valid']:
raise reports.SoundLabError(f"{label}/{name}: partial/invalid report: {'; '.join(parsed['issues'])}")
if parsed['integrity'] != {'record_count': 'VERIFIED', 'checksum_crc16': 'VERIFIED'}:
raise reports.SoundLabError(f'{label}/{name}: count/checksum not both verified')
if identity_issues:
raise reports.SoundLabError(f"{label}/{name}: {'; '.join(identity_issues)}")
if parsed['metadata'].get('RUN') != name[3:7]:
raise reports.SoundLabError(f'{label}/{name}: RUN does not match filename')
case_summary = []
for case in parsed['cases']:
if case['human'] == 'HEARD':
raise reports.SoundLabError(f'{label}/{name}/{case["id"]}: native automation must not fabricate HUMAN=HEARD')
run_result['repeat_observed'] |= case['repeat'] > 0
run_result['unsure_recorded'] |= case['human'] == 'UNSURE'
case_summary.append({'case': case['id'], 'repeat': case['repeat'], 'auto': case['auto'], 'human': case['human'],
'vector_crc16': case['fields']['VECTOR_CRC16']})
run_result['reports'].append({'filename': name, 'sha256': item['sha256'], 'bytes': item['byte_count'],
'complete': True, 'integrity': parsed['integrity'], 'cases': case_summary})
if label in ('6809', '6309') and (not run_result['repeat_observed'] or not run_result['unsure_recorded']):
raise reports.SoundLabError(f'{label}: required repeat and UNSURE inputs were not recorded')
outcome['runs'][label] = run_result
for name, data in extracted['6809'].items():
if extracted['engineering'].get(name) != data:
raise reports.SoundLabError(f'Engineering continuation modified or removed original 6809 report {name}')
added = sorted(set(extracted['engineering']) - set(extracted['6809']))
if not added:
raise reports.SoundLabError('Engineering continuation did not create any additional reports')
outcome['engineering_original_reports_byte_identical'] = True
outcome['engineering_new_reports'] = added
outcome['passed'] = True
return outcome
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--build-dir', type=Path, default=Path('.build/sound-lab'))
parser.add_argument('--receipt', type=Path, help='Optional JSON receipt; no output files are written by default')
parser.add_argument('--overwrite', action='store_true', help='Explicitly replace an existing regular receipt file')
args = parser.parse_args(argv)
try:
result = qualify(args.build_dir)
if args.receipt:
inputs = [args.build_dir / 'SOUNDLAB-manifest.json', args.build_dir / 'SOUNDLAB.DSK']
inputs.extend(args.build_dir / 'qualification' / f'{label}-reports.dsk' for label in ('6809', '6309', 'engineering'))
if any(args.receipt.resolve() == path.resolve() or (args.receipt.exists() and args.receipt.samefile(path)) for path in inputs):
raise reports.SoundLabError('Receipt would replace an input')
reports.write_outputs({args.receipt: (json.dumps(result, indent=2) + '\n').encode('utf-8')}, args.overwrite)
print(f"PASS Sound Lab reports: build {result['build_id']}; " + ', '.join(f"{label}={len(run['reports'])}" for label, run in result['runs'].items()))
print('Verified complete reports, checksums/counts, manifest identities, repeated/UNSURE inputs, unchanged BIN/BAS and retained originals.')
print('No HUMAN=HEARD result or physical/listening acceptance is claimed.')
return 0
except (OSError, ValueError, KeyError, TypeError) as error:
print(f'Sound Lab report qualification failed: {error}', file=sys.stderr)
return 1
if __name__ == '__main__':
raise SystemExit(main())