view 00README.txt @ 1:704b2c9dc19e default tip

Remove extraneous unused and incorrect definition
author William Astle <lost@l-w.ca>
date Wed, 02 Jan 2019 10:11:19 -0700
parents 605ff82c4618
children
line wrap: on
line source

The source files here build to byte accurate versions of the following ROMs
that are found in various Color Computers:

Color Basic 1.0
Color Basic 1.1
Color Basic 1.2
Color Basic 1.3
Extended Color Basic 1.0
Extended Color Basic 1.1
Extended Color Basic 2.0 (Coco3)
Disk Extended Color Basic 1.0 (shows 2.0 on the Coco3)
Disk Extended Color Basic 1.1 (shows 2.1 on the Coco3)

The source files are based on the contents of the Unravelled series as
published by Spectral Associates as updated by Walter K. Zydhek. As such,
most of the symbols used will line up with those in the Unravelled series.
There are, however, some significant changes.

* All source has been convered to use a semicolon to introduce comments
  instead of relying on the implied end of line comments.

* Spaces have been used to line up the columns instead of tabs. 16 spaces
  are allowed for the label field. 32 spaces are allowed for the instruction
  (both opcode and operand, separated by a single space) in most cases, and
  the majority of comments will line up starting at column 49.

* Source code has been largely converted to lower case. This is a personal
  preference, but it also feels a bit less "shouty". Labels, however, have
  retained their original case.

* C style hexadecimal constants have been used in most cases.

* Features specific to LWASM have been used to create fairly clean listing
  files for the various ROMs. LWASM is, of course, required to build the
  ROMs from this source.

* The comments have been extensively rewritten. Any typos now extant in said
  comments are entirely the fault of the guy writing them.

* A few cases where numeric addresses were used instead of labels have been
  corrected.

Comment Accuracy
================

This is important to point out. While reasonable efforts have been made to
ensure that the comments accurately reflect what the relevant code is doing,
there are certainly errors that have crept in, or been duplicated from the
original disassembly sources.

In some cases, the code is just convoluted enough that no reasonable
comments can do it justice. This is especially true in relation to the
floating point implementation.

In other cases, what the code is doing is relatively clear but why it does
it is not. In other cases, truly understanding what the code is doing
requires a much more advanced understanding of mathematics or other fields
than the commenter has. In these cases, inaccurate comments could well be
present but the commenter would have no way of knowing for sure.

There are also many cases in the original Unravelled comments where the
comments were just plain wrong or had the sense of a flag or other test
completely reversed. These have been corrected where they were detected, but
there is a great deal of code across the combined 96K of ROM code.

Finally, some care has been taken to avoid comments the merely describe what
the instruction itself does in a manner that could have come right out of a
CPU reference manual. For instance, an instruction like "STX V4D" is better
left with no comment rather than writing "store X in V4D".


Future Updates
==============

Since this code is basically frozen, any future modifications will be for
aesthetic reasons. Most notably, replacing synthetic address based labels
with more sensible ones would be beneficial. So would replacing variable
names with more descriptive names since the assembler in use supports much
longer symbol names.

That said, any updates into the future must preserve the output as byte
identicial for obvious reasons.