AI-Generated Documentation Pass - #1
Open
spectecjr wants to merge 5 commits into
Open
Conversation
Attempted to put together a starter-pack for the most confusing pieces of the SAM ROM, in more detail than the Annotated SAM BASIC pdf normally gives, particularly focusing on SAM BASIC, the FPC, and parameter passing using CALL/USR/USR$. This was generated by Claude Fable (thanks for the free tokens, Anthropic) reading the source code. As with everything AI, it may contain errors, but everything I've checked so far appears to be legit and match what I've seen digging through the assembly source recently. (And it's not like the technical manual/other docs don't have errors in them anyway...) - Cookie of Entropy (Simon Cooke)
Needed to match GitHub conventions (straight LaTeX using $ / $$)
Owner
|
Thanks! The docs look like a good overview for anyone looking at the ROM code, and something nobody was every going to write from scratch. I'd imagine future models will be able to check/update it, looking for any issues. I've only had a bit of a skim over the details, but enough to be happy with it. I made a comment on the latest commit that doesn't seem to be linked to this PR, related to GitHub formatting. Would you be able to see if it can fix the remaining LaTex formatting before it gets merged in? |
Three bodies of documentation, all derived from the ROM source itself
rather than from the original printed manuals.
annotated/ -- a parallel copy of the ROM source documented as a modern
codebase would be: file-level overviews, per-routine contracts (entry,
exit, registers, notes), inline explanation of non-obvious code, and
named constants in place of magic numbers. All 39 source files, plus a
new equates.asm. pyz80 builds the tree to an image byte-identical to the
one built from the original source; verify_annotated.py checks
equivalence from the text alone, which pinpoints which line differs when
a build fails.
docs/user-manual/ -- a 21-part manual taking a reader from their first
PRINT to writing extensions: 15 chapters, an A-Z reference covering
every keyword and function, and appendices for the 56 error reports, the
character set, the token map and the operator priorities. Chapter 14
tabulates every system variable reachable through SVAR, marked for
whether it is safe to write.
docs/extending-basic.md -- the MTOKV/CMDV/RST28V/PRTOKV hooks with their
exact entry and exit contracts, the (small) budget of free tokens, where
extension code has to live and how to carve room for it, and four worked
examples that assemble with pyz80.
Also adds font-rendering.md and hudg.md, and cross-references the new
documents from constants.md, memory-map.md and source-files.md.
Several things widely believed about SAM BASIC turn out not to hold for
ROM 3.0. The docs say so, with the evidence:
* LET is mandatory. A bare name starting a statement is parsed as a
procedure call, so "x = 1" gives Missing DEF PROC.
* MOD and DIV bind at priority 14 -- tighter than * and /.
* INK and PEN share one token, so INK 3 lists back as PEN 3.
* The ROM has no external-command mechanism. Nothing reads XCMDP, and
nothing sets the call buffer's "external" bit -- but the original
comments show what was intended, and extending-basic.md reconstructs
the design and finishes it.
Written with AI assistance and not tested on hardware or in an emulator;
every document carries that warning.
Adds a reference for the three common extensions, tags every feature in
the user manual that needs one, and corrects the errors an
error-checking pass turned up in both the annotated source and the docs.
docs/dos-and-extensions.md is new. It covers what each product adds, how
each attaches itself to the ROM, and the combined token map. The
SAMDOS 2 and MasterDOS material is read from their published sources
and can be checked line by line; the MasterBASIC material is from its
manual, since
no source was available.
Four tags now mark anything that is not plain ROM 3.0 -- [DOS], [SD2],
[MD] and [MB] -- used consistently across the manual. Appendix D
previously flagged DOS commands with a bare "D"; it now uses the same
tags as everything else.
The extensions turn out to sit exactly where the ROM leaves room.
MasterDOS and MasterBASIC take command tokens &F7-&FD and put their own
functions below &3B, a range the evaluator rejects outright and which
therefore cannot collide with the ROM. MasterBASIC's XVAR and NVAL
occupy &68 and &6A -- the two free calculator slots -- with exactly the
argument and result types the ROM's priority tables fix for them.
Three findings contradicted extending-basic.md, which is corrected:
* EVALUV can implement functions after all. MasterDOS recovers NUMCONT
and STRCONT at run time by walking the ROM from the vector's own
return address, rather than hard-coding them.
* Neither system-page hole is free in practice. MasterDOS installs
stubs at &4BA0 and &5896.
* Neither DOS uses XCMDP, RST8V or the calling buffers. Both trap
error 29 at their &4203 entry and dispatch on the token, and both
offer an ONERR vector of their own -- DVAR 25 in SAMDOS 2, DVAR 33
in MasterDOS. The dot-command convention was never adopted by
either.
ERROR FIXES
The annotated tree still assembles byte-identical to the original; all
the .asm changes are comments.
* README.md gave the wrong address for the PLC/plc difference against
ROM30. It is &F5F8-&F5FA, in the banner at UMVAL.
* scrfn.asm labelled the DUMP command's CHR$ branch as SCREEN$, and as
a text copy. The code tests CHR$, and both branches fall through to
the graphics value -- A = 0 is only reachable through the JTCOPY
jump-table entry. The original's own "TEXT COPY" label is
contradicted by its code, which looks like a missing JR JTCOPY; the
annotation now says so.
* main.asm overstated the jump table as &0100-&0192. It ends at &018F.
* vars.asm read UWBOT's "9 PIX" as nine spare pixels. It is the
nine-pixel row height; the leftover is three scans, becoming LSOFF.
* text.asm presented two of the author's design musings -- symbol
characters in PROC names, and "." for external commands -- as
implemented fact. Neither works; the original even ends the first
with a question mark.
* printfp.asm claimed PFSTRSC is used by PRINT USING. There is no
PRINT USING, and nothing calls PFSTRSC.
* equates.asm described CALLBUFEXT as being set for external commands.
It is never set or tested.
* miscx2.asm called a positive length negated.
And in the documentation:
* FRACLIM was documented as a usable setting. It is not: PFSTRS
rewrites it to 6 before every conversion, so a POKE never survives.
Chapter 3's example did not work.
* DUMP and DUMP CHR$ were described as text and graphics dumps. Both
pass the same value to the driver.
* Appendix C's control-code table conflated what the editor does with
a key code and what printing it does. They differ for 0-5, 7, 15 and
24-31, which print as "?".
* OFF and WRITE were marked reserved and unused. Both DOSes use them:
PROTECT OFF, HIDE OFF, and WRITE for record files.
* DVAR returns the address of a DOS variable, not its value.
* DEVICE M was documented as the way to select a disk. No SAM DOS
uses M; both SAMDOS 2 and MasterDOS take D, as in DEVICE D2 and the
"D1:name" prefix. The original source's own example comment says M,
which is where this came from. Drive numbers are 1-2 under SAMDOS 2;
MasterDOS adds 3-7 as RAM disks.
* The manual showed ".dir" and ".copy" as if external commands
existed. They do not: the ROM rejects a leading full stop and
neither DOS adds one, so a dot command works only where a later
utility has claimed CMDV. Four passages reworded.
DISK OPERATIONS
Eight DOS commands in appendix A had a one-line description where every
other entry has a syntax block. COPY, DIR, ERASE, FORMAT, HIDE, MOVE,
PROTECT and RENAME now match the house style, with syntax read from the
DOS parsers rather than guessed, and OPEN and CLOSE gain their DOS
forms.
Chapter 11 gains two sections. 11.7 covers serial OPENTYPE files: the
IN / OUT / RND forms, INP$, the FSTAT options, and why CLOSE is what
finalises a file's length. 11.8 covers the filesystem -- what a disk
holds, and what each command changes across the directory entry, the
data sectors and the allocation map. Two traps get their own headings:
ERASE frees sectors without destroying data, and under MasterDOS opening
or
closing a file moves the BASIC program, which is what MasterBASIC's
OPEN BLOCKS exists to prevent.
VERIFICATION
Checks run over the result, beyond the byte-identical build:
* 257 system-variable addresses against vars.asm
* all 56 error messages, decompressed from the assembled image
* 193 keyword and token codes, parsed from KEYWTAB in the image
* 48 jump-table entries against main.asm
* every cross-document link and anchor
Two pre-existing broken anchors in source-files.md were fixed in
passing.
Still not tested on hardware or in an emulator; every document carries
that warning.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Attempted to put together a starter-pack for the
most confusing pieces of the SAM ROM, in more
detail than the Annotated SAM BASIC pdf normally
gives, particularly focusing on SAM BASIC, the
FPC, and parameter passing using CALL/USR/USR$.
This was generated by Claude Fable (thanks
for the free tokens, Anthropic) reading the
source code.
As with everything AI, it may contain errors,
but everything I've checked so far appears to be
legit and match what I've seen digging through
the assembly source recently. (And it's not like
the technical manual/other docs don't have errors
in them anyway...)