Mercurial > hg > index.cgi

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

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
1 The source files here build to byte accurate versions of the following ROMs
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
2 that are found in various Color Computers:
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
3
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
4 Color Basic 1.0
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
5 Color Basic 1.1
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
6 Color Basic 1.2
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
7 Color Basic 1.3
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
8 Extended Color Basic 1.0
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
9 Extended Color Basic 1.1
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
10 Extended Color Basic 2.0 (Coco3)
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
11 Disk Extended Color Basic 1.0 (shows 2.0 on the Coco3)
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
12 Disk Extended Color Basic 1.1 (shows 2.1 on the Coco3)
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
13
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
14 The source files are based on the contents of the Unravelled series as
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
15 published by Spectral Associates as updated by Walter K. Zydhek. As such,
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
16 most of the symbols used will line up with those in the Unravelled series.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
17 There are, however, some significant changes.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
18
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
19 * All source has been convered to use a semicolon to introduce comments
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
20 instead of relying on the implied end of line comments.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
21
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
22 * Spaces have been used to line up the columns instead of tabs. 16 spaces
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
23 are allowed for the label field. 32 spaces are allowed for the instruction
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
24 (both opcode and operand, separated by a single space) in most cases, and
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
25 the majority of comments will line up starting at column 49.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
26
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
27 * Source code has been largely converted to lower case. This is a personal
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
28 preference, but it also feels a bit less "shouty". Labels, however, have
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
29 retained their original case.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
30
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
31 * C style hexadecimal constants have been used in most cases.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
32
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
33 * Features specific to LWASM have been used to create fairly clean listing
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
34 files for the various ROMs. LWASM is, of course, required to build the
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
35 ROMs from this source.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
36
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
37 * The comments have been extensively rewritten. Any typos now extant in said
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
38 comments are entirely the fault of the guy writing them.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
39
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
40 * A few cases where numeric addresses were used instead of labels have been
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
41 corrected.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
42
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
43 Comment Accuracy
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
44 ================
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
45
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
46 This is important to point out. While reasonable efforts have been made to
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
47 ensure that the comments accurately reflect what the relevant code is doing,
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
48 there are certainly errors that have crept in, or been duplicated from the
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
49 original disassembly sources.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
50
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
51 In some cases, the code is just convoluted enough that no reasonable
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
52 comments can do it justice. This is especially true in relation to the
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
53 floating point implementation.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
54
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
55 In other cases, what the code is doing is relatively clear but why it does
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
56 it is not. In other cases, truly understanding what the code is doing
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
57 requires a much more advanced understanding of mathematics or other fields
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
58 than the commenter has. In these cases, inaccurate comments could well be
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
59 present but the commenter would have no way of knowing for sure.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
60
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
61 There are also many cases in the original Unravelled comments where the
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
62 comments were just plain wrong or had the sense of a flag or other test
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
63 completely reversed. These have been corrected where they were detected, but
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
64 there is a great deal of code across the combined 96K of ROM code.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
65
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
66 Finally, some care has been taken to avoid comments the merely describe what
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
67 the instruction itself does in a manner that could have come right out of a
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
68 CPU reference manual. For instance, an instruction like "STX V4D" is better
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
69 left with no comment rather than writing "store X in V4D".
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
70
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
71
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
72 Future Updates
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
73 ==============
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
74
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
75 Since this code is basically frozen, any future modifications will be for
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
76 aesthetic reasons. Most notably, replacing synthetic address based labels
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
77 with more sensible ones would be beneficial. So would replacing variable
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
78 names with more descriptive names since the assembler in use supports much
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
79 longer symbol names.
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
80
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
81 That said, any updates into the future must preserve the output as byte
605ff82c4618 Initial check in with cleaned up sources
William Astle <lost@l-w.ca>
parents:
diff changeset
82 identicial for obvious reasons.