Mercurial > hg > index.cgi

annotate README.txt @ 125:0607e4e20702

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Correct offset error for keyword table lookup
author William Astle <lost@l-w.ca>
date Sun, 07 Jan 2024 20:35:51 -0700
parents 1c1a0150fdda
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
1 This is the LWBasic project. Its goal is to create a replacement Basic for
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
2 the TRS80 Color Computer. This Basic will not be binary compatible with the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
3 stock ROM. In particular, any various peeks, pokes, executes, and the like
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
4 intended to mess with the interpreter internals are unlikely to work, and,
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
5 in fact, may be completely detrimental.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
6
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
7 Additional detailed documentation can be found under docs/.
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
8
0
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
9 There are two versions of LWBasic. One is for the Coco 1 and 2. The other
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
10 is for the Coco 3. The primary differences between the two are in the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
11 startup code and features that rely on the existence of Coco 3 hardware. The
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
12 main differences for the Coco 3 version are:
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
13
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
14 * 32/40/64/80 column text modes with attributes
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
15 * 256/320/512/640 column bitmap graphics with up to 16 colours (256/320)
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
16 or 4 colours (512/640)
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
17 * palette register setting
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
18 * graphics and text screen located outside main program memory
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
19 * disk I/O buffers located outside main program memory
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
20 * separate heaps for strings, scalars, arrays, and program text not limited
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
21 to the 64K address space of the CPU
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
22 * ROM/RAM copy at startup and initialization of Coco 3 specific hardware;
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
23 defaulting to the 80 column text screen
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
24
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
25 Both versions can either be installed in ROM or loaded from disk or tape.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
26 In the case of loading from disk or tape, the machine must have at least
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
27 64K of RAM. The loadable versions do not include certain initalization
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
28 routines that are only relevant to cold starting the hardware.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
29
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
30 For the Coco 3 version, the ROM is a single 32K chunk intended to replace
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
31 the 32K internal ROM. For the Coco 1/2 version, there are three chunks: an
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
32 "Extended Color Basic" chunk (8K for the ECB socket), a "Color Basic" chunk
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
33 (8K for the CB socket), and "Disk Extended Color Basic", a 16K chunk
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
34 intended to be installed in a cartridge ROM, probably a disk controller. On
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
35 machines with a single 16K internal ROM, the "Extended Color Basic" and
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
36 "Color Basic" chunks should arranged with "Extended Color Basic" at the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
37 lowest address and "Color Basic" immediately above.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
38
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
39 An important note about the hardware interrupt vectors in the ROMs: the Coco
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
40 1/2 get the FFFx vectors from the top 16 bytes of the "Color Basic" chunk.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
41 The Coco 3 gets the FFFx vectors from the top 16 bytes of the 32K internal
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
42 ROM.
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
43
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
44 Note that LWBasic does not look for the DK signature of a Disk Basic ROM
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
45 and, thus, will not autostart whatever Disk Basic you happen to have
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
46 installed. This is most relevant on a Coco 3 where the upper 16K of the
fbb8f369ce76 Initial project creation with README file
William Astle <lost@l-w.ca>
parents:
diff changeset
47 LWBasic ROM is internal instead of in a cartrige.
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
48
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
49
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
50 Numbers
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
51 =======
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
52
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
53 LWBasic has two numeric types: a 32 bit signed integer, stored as two's
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
54 complement and a decimal floating point type stored in packed BCD with
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
55 10 digits of precision and a base 10 exponent range of -63 to +63
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
56
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
57 The BCD format using 48 bits is stored as follows:
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
58
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
59 Offset Bits Content
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
60 0 1 Sign bit - 1 for negative
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
61 1 7 Decimal exponent with a bias of 64; 0 indicates a value of 0
120
1c1a0150fdda Add documentation of bytecode and parsing scheme
William Astle <lost@l-w.ca>
parents: 85
diff changeset
62 8 40 10 packed BCD digits of the significand
85
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
63
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
64 It is worth noting the reason for using the BCD format instead of binary
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
65 floating point. Because interactions with the computer are typically in base
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
66 10, it makes sense to avoid the horrendous complications of attempting to
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
67 maximize the accuracy of converting binary floating point to decimal and
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
68 back again. While this is trivial for integers, it is non-trivial for
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
69 floating point where the variations in accuracy and the need for rounding is
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
70 unavoidable.
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
71
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
72 At the expense of some extra CPU cycles for doing the calculations, base 10
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
73 accuracy is preserved, at least to the precision limit of the data type.
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
74 This also allows pre-parsing numbers and being able to display them again
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
75 accurately when generating a program listing, even if extra nonsignificant
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
76 digits like trailing decimal zeroes are not reproduced.
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
77
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
78 It is, however, critical to note that despite the BCD representation, these
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
79 values are still floating point and have the inherent inaccuracies of all
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
80 limited precision data types. The simple difference is that it makes the
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
81 numbers in the computer behave exactly like scientific notiation with no
663d8e77b579 Implmement BCD floating point and update number parsing and printing
William Astle <lost@l-w.ca>
parents: 0
diff changeset
82 unexpected surprises.