8 BIF documentation Copyright 1992, 2000, 2019 Joel Matthew Rees
\r
9 BIF source and object Copyright 1992, 2000, 2019 Joel Matthew Rees
\r
10 https://ja.osdn.net/projects/bif-6809/
\r
13 In the spirit of fig-FORTH, the author grants permission as follows:
\r
15 Permission to use, copy, modify, and/or distribute this software for
\r
16 any purpose with or without fee is hereby granted, provided that the
\r
17 accompanying copyright notices and this permission notice appear in
\r
20 THE SOFTWARE IS PROVIDED “AS IS” AND ISC DISCLAIMS ALL WARRANTIES
\r
21 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
\r
22 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY
\r
23 SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
\r
24 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
\r
25 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
\r
26 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
\r
29 (This is essentially the ISC license.)
\r
31 If the copyright notices in this file and the README.TXT file are
\r
32 retained, including that file and this with your distribution will
\r
33 fulfill the copyright notice obligation.
\r
35 But you really should include both anyway, just to be kind to the
\r
36 people who receive it.
\r
40 BIF is architecturally derived from fig-FORTH. fig-FORTH comes courtesy
\r
41 of the FORTH INTEREST GROUP, PO Box 1105, San Carlos, CA 94070.
\r
43 This is not a commercial product; it was a student project, use it at
\r
44 your own risk. No warranty whatsoever is made concerning it. (If, by
\r
45 chance, anyone is interested in using BIF in a commercial product, I
\r
46 would appreciate knowing about it in advance.) The author's intent is
\r
47 only to make it available for experimentation, and it should be treated
\r
48 as strictly experimental software. DO NOT ATTEMPT TO ACCESS ORDINARY
\r
49 DISKS FORMATTED FOR USE BY OTHER OPERATING SYSTEMS WHILE BIF IS RUNNING!
\r
51 Contact as of January 2000:
\r
52 http://reiisi.blogspot.com
\r
53 joel.rees+knock@gmail.com
\r
54 https://defining-computers.blogspot.com/
\r
55 https://ja.osdn.net/users/reiisi/
\r
56 https://sourceforge.net/u/reiisi/profile/
\r
60 *******************************************************************************
\r
64 BIF (BInary tree, fig-FORTH) is a dialect of FORTH for the Tandy Color
\r
65 Computer. It is a direct-threaded version of the pre-FORTH-79 fORTH
\r
66 interest group publication of FORTH (fig-FORTH), using a non-standard
\r
67 binary tree dictionary structure. The direct-threading mechanism uses
\r
68 the direct-page addressing mode of the 6809, and thus may not be easily
\r
69 adaptable to FORTH-83. It also uses absolute addressing, and thus does
\r
70 not comform to the requirements of OS-9. (I was working on an
\r
71 indirect-threaded version of BIF for OS-9 in my spare time, it
\r
72 has not happened at this point.)
\r
74 BIF.BIN is the executable object; after LOADMing it, EXEC the address
\r
75 &H1300 (see below). The assembler used is Disk EDTASM+. I used TSEdit
\r
76 to generate the source files in EDTASM+ format:
\r
78 line-number SPACE [label] TAB mnemonic etc. LF
\r
80 Using a text editor (etc.) to replace the macros with their expansions
\r
81 should make it compatible with most other assemblers. An object which
\r
82 will run under the EDTASM+ "stand-alone" debugger may be generated by
\r
83 changing ORG $1200 in BIF.ASM to ORG $3F00.
\r
85 The archive contains the BIF/FORTH source for several utilities, the
\r
86 assembler, and double integer definitions (TOOLS.G00) and a definition
\r
87 pairing example (PAIRS.G28) useful for making paired lists. Using
\r
88 TOOLS.G00 and PAIRS.G28 directly will require moving the two files to
\r
89 their original granules, 0 and 28, on an ECB disk. Once they are moved,
\r
90 protecting the BIF screens with ECB directory entries may be a good
\r
91 idea. But resist the temptation to use a text editor on them. Messing
\r
92 with the whitespace will move the source code out of alignment with the
\r
93 physical FORTH/BIF screens, and thus cause the source code not to load.
\r
95 If you want to look at these two files with an editor, use the 32col.c
\r
96 program to look. At present, I have no means of converting them back.
\r
98 If you want to send me money, that sounds great, but contact me by
\r
101 The documentation which follows is written in the standard FORTH
\r
102 documentation style. It is not intended as a primer or study guide.
\r
103 Brodie's Starting FORTH, Winfield's THE COMPLETE FORTH, or some other
\r
104 text is suggested to those unfamiliar with FORTH. Much of the code and
\r
105 examples should work as shown in the textbooks I recommend Leo Brodie's
\r
106 work, because he points out most of the places the user will have to
\r
107 refer to this documentation. Some of the descriptions are incomplete,
\r
108 particularly where definitions are intended to be used inside other
\r
111 The object contains a simple one-sector editor (for 32-column screens)
\r
112 in the EDITOR vocabulary. It does not provide search and replace, but
\r
113 it is sufficient, for the patient, to write code. My apologies for it.
\r
114 I did not have a Color Computer 3 when I wrote the original code, and
\r
115 haven't had the time to update it. Those with access to the fig-FORTH
\r
116 Installation Manual should have no problem installing the editor shown
\r
119 The assembler in the BIF screens is a full postfix assembler. The
\r
120 double integer screens show a quick example of its use.
\r
123 *******************************************************************************
\r
124 Getting BIF Running
\r
127 Before you start, remember that BIF has the same post-fix grammar as
\r
128 FORTH. Think Reverse Polish, as in HP calculators.
\r
130 Computer: Comments:
\r
133 LOADM "BIF.BIN" from whichever drive it is on, then remove all disks and
\r
134 EXEC &H1300 BIF should tell you it is running with
\r
137 At this point, see if BIF is really running by typing
\r
138 VLIST and hitting ENTER. You should see a listing of your
\r
139 main vocabulary (symbol table) which should run on for
\r
140 about 200 entries, and then the computer responds with
\r
141 OK If this doesn't happen, you have a bad object file, get
\r
142 a new copy. Otherwise, you have BIF!
\r
144 If you have my BIF screens disk, put it in drive 0.
\r
146 6 LOAD to load the utilities starting at screen 6. After the
\r
147 utilities are loaded, you can load the assembler by
\r
151 If you don't have the BIF screens disk with the error
\r
153 0 WARNING ! and BIF responds with
\r
154 OK but now tells you error numbers instead of messages.
\r
156 Okay, a few examples:
\r
160 puts the ascii character 42 (asterisk if the current BASE is DECIMAL) on
\r
165 prints the product of 5 and 6 (30, base ten) on the output device.
\r
167 DECIMAL : CHARS 32 DO I . I EMIT CR LOOP ;
\r
170 will set up a BIF "word" called CHARS, which, being invoked on the second
\r
171 line, will print the characters and hexadecimal ascii codes from SPACE
\r
172 up to, but not including, DASH.
\r
174 The BIF screens disk should always be in drive 0 if you want real error
\r
175 messages. If you want to look at the message text, the messages are at
\r
176 the front of TOOLS.G00, after the directory screen and title screen.
\r
177 Each message takes exactly 32 characters, including spaces and
\r
178 non-printing characters. Numbering starts with 0. If you have some
\r
179 other disk in drive 0 you will get funny and not exactly intelligent
\r
180 error messages. I know it's weird, but I was following the fig-FORTH
\r
181 model, which is designed for very limited memory.
\r
183 If you haven't been able to put the BIF screens disk together, you don't
\r
184 really need it to play around with BIF, but do clear the WARNING
\r
185 variable so BIF will know error messages are not available. Aside from
\r
186 the error messages in drive 0, there is nothing special about screens
\r
187 disks, except they do not have directory tracks. You should generally
\r
188 not put them in your drives when running under BASIC (DECB), OS-9 or
\r
189 some other system. By tradition, programmers use the first several
\r
190 screens as a hand-typed directory. You can format fresh BIF disks with
\r
191 either Disk Extended Color BASIC's DSKINI or OS-9's format. BIF ignores
\r
192 the directory information both systems write, so you also generally
\r
193 should not put a real DECB or OS-9 disk in while BIF is running.
\r
195 If you do format with OS-9, format single-sided (I used DECB's disk
\r
196 interface routines so BIF can't do double sided) with as many tracks as
\r
197 you want. To use the extra tracks, or a third or fourth drive, you will
\r
198 need to modify the DRIVE-OFFSET array. Pick a standard disk
\r
199 configuration and stick with it.
\r
201 An important word of warning. BIF, like FORTH, uses buffered I/O. Your
\r
202 screens are not actually saved to disk until you cause the system to
\r
203 need enough new buffers to write your editing back to the disk. To
\r
204 force the system to save the buffers, give BIF the SAVE-BUFFERS command.
\r
207 *******************************************************************************
\r
211 EDITOR gets you into the EDITOR vocabulary.
\r
212 0 QLIST lets you look at the first sector of the directory.
\r
213 4 B/SCR * QLIST lets you look at the first eight error messages.
\r
214 DECIMAL makes sure your conversion base is base ten.
\r
216 lets you edit the first sector of the pairing example.
\r
217 Use the cursor keys to move around; use the BREAK key to
\r
218 get out. If you modified something you don't want to
\r
220 EMPTY-BUFFERS and ENTER. If you want to make sure your changes are
\r
221 written to the disk, type
\r
222 SAVE-BUFFERS and ENTER.
\r
224 The QUICK editor is in the EDITOR vocabulary. It is available at boot
\r
225 up. You'll need to get into the EDITOR vocabulary, to access it. Pass
\r
226 it a sector number, not a screen number. Multiplying by B/SCR (which
\r
227 happens to be 4) will convert a screen number to a sector number. Add
\r
228 1, 2, or 3 to the base sector number of a screen to get the sector
\r
229 numbers for the second, third, and fourth sectors of that screen.
\r
231 The editor has no find/replace or block functions. Again I apologize
\r
232 for the editor, but I found it surprisingly workable. Note that the
\r
233 utility screens contain routines to move/copy sectors, so all is not
\r
234 entirely mud. One more glitch. Lower case letters will show as VDG
\r
235 codes until you run the cursor over them. What can I say?
\r
237 During editing, all arrow keys are cursor controls. Use SHIFT-LEFTARROW
\r
238 for destructive backspace, SHIFT-DOWNARROW for `[' left bracket,
\r
239 SHIFT-RIGHTARROW for `]' right bracket, SHIFT-UPARROW for `_' underscore
\r
240 (back-arrow on CoCo2). SHIFT-CLEAR escapes the UP-ARROW to provide the
\r
241 `^' caret. SHIFT-CLEAR also escapes itself to provide the backslash.
\r
243 Perhaps this is as good a place as any to mention a few points of
\r
244 terminology. A block is a sector. Sectors are numbered sequentially
\r
245 from 0. Sector numbering continues sequentially from drive n to drive
\r
246 n+1, see DRIVE-OFFSET, but also see OFFSET. A SCREEN is a kilobyte
\r
247 worth of blocks, in this case, four 256-byte sectors. SCREEN numbering
\r
248 also begins with 0. (SCREENs are called SCREENs because a SCREEN can be
\r
249 displayed on 16 lines of a 64-column CRT screen.) You will notice that
\r
250 a CoCo 2 can't properly display and edit a whole SCREEN. Finally,
\r
251 forward blocks are control constructs, not disk sectors.
\r
254 *******************************************************************************
\r
255 The BIF Virtual Machine
\r
259 UP [DP] pointer to the per-USER variable table (USER Pointer)
\r
260 IP Y pointer to the next definition (Instruction Pointer)
\r
261 RP S return/control stack pointer
\r
262 SP U parameter/data stack pointer
\r
263 W [S] pointer to executing definition's parameter field
\r
265 The BIF Virtual Machine
\r
268 { bifc_vm.c bif.m bifdp.a
\r
269 NEXT ( --- ) jmp [,y++] (macro in bif.m)
\r
270 Causes the next definition to execute.
\r
272 DOCOL ( *** IP ) jsr <XCOL (see bif.m, bifdp.a)
\r
273 Characteristic of a colon (:) definition. Begins execution of a
\r
274 high-level definition, i. e., nests the definition and begins
\r
275 processing icodes. Mechanically, it pushes the IP (Y register)
\r
276 and loads the Parameter Field Address of the definition which
\r
277 called it into the IP.
\r
279 { symbol.c bif.m bifdp.a
\r
280 DOVAR ( --- vadr ) jsr <XVAR (bif.m, bifdp.a)
\r
281 Characteristic of a VARIABLE. A VARIABLE pushes its PFA address
\r
282 on the stack. The parameter field of a VARIABLE is the actual
\r
283 allocation of the variable, so that pushing its address allows
\r
284 its contents to be @ed (fetched). Ordinary arrays and strings
\r
285 that do not subscript themselves may be allocated by defining a
\r
286 variable and immediately ALLOTting the remaining space.
\r
287 VARIABLES are global to all users, and thus should have been
\r
288 hidden in resource monitors, but aren't.
\r
290 DOCON ( --- n ) jsr <XCON (bif.m, bifdp.a)
\r
291 Characteristic of a CONSTANT. A CONSTANT simply loads its value
\r
292 from its parameter field and pushes it on the stack.
\r
294 DOUSER ( --- vadr ) jsr <XUSER (bif.m, bifdp.a)
\r
295 Characteristic of a per-USER variable. USER variables are
\r
296 similiar to VARIABLEs, but are allocated (by hand!) in the
\r
297 per-user table. A USER variable's parameter field contains its
\r
298 offset in the per-user table.
\r
300 DOVOC ( --- ) jsr <XVOC (bif.m, bifdp.a)
\r
301 Characteristic of a VOCABULARY. A VOCABULARY stores a pointer
\r
302 to itself in the current interpretation ROOT per-USER variable.
\r
303 It contains a pointer to the definition at the root of its
\r
304 symbol table tree. This allows the symbol table routines to
\r
305 treat the root as a leaf node. This is also not standard FORTH!
\r
307 ( --- PFA ) ( *** IP ) jsr <XDOES (routine in bifdp.a)
\r
308 Characteristic of a DOES> defined word. The characteristics of
\r
309 DOES> definitions are written in high-level icodes rather than
\r
310 machine level code. The first parameter word points to the
\r
311 high-level characteristic. This routine's job is to push the
\r
312 IP, load the high level characteristic pointer in IP, and leave
\r
313 the address following the characteristic pointer on the stack so
\r
314 the parameter field can be accessed.
\r
316 The following are not standard FORTH characteristics:
\r
318 DO1ARR ( index --- eadr ) jsr <X1ARR (bif.m, bifdp.a)
\r
319 Characteristic of a linear array. Linear arrays take the top
\r
320 word on the stack as an index to the array, and return the
\r
321 address of the element indexed. So this routine subtracts the
\r
322 base index of the array, limit checks the result, then
\r
323 multiplies by the size of the array elements. If the index is
\r
324 out of bounds, it returns a NULL pointer (0). At some point I
\r
325 intended to implement multi-dimensional arrays in a similar
\r
326 manner, but I haven't. It would be a quick and interesting
\r
327 project for anyone interested.
\r
329 DOUCON ( --- n ) jsr <XUCON (bif.m, bifdp.a)
\r
330 Characteristic of a USER variable treated as a CONSTANT, i. e.,
\r
331 fetches the value stored at the specified offset in the per-user
\r
334 ( --- d ) jsr <XDCON (bifdp.a)
\r
335 Characteristic of a double integer constant; the parameter field
\r
336 contains two words instead of one, both of which get pushed.
\r
339 ADDTOP (MACRO in BIF.M) is not a characteristic; is used in several
\r
340 routines to add a value to the top of stack.
\r
343 One of the primary problems with extending BIF is that calls to the
\r
344 built-in characteristics are not conform to ;CODE. Defining definitions
\r
345 which use (;CODE) to establish the characteristics of the
\r
346 sybmbols/definitions they define will hav a three-byte code field, where
\r
347 the built-in compiling definitions -- VARIABLE, (1ARRAY, etc.,)
\r
348 CONSTANT, USER, :, and VOCABULARY have two-byte code fields. One
\r
349 specific example of the difficulties this can create is that
\r
350 vocabularies with special properties built in BIF, rather than by hand,
\r
351 can't be searched by BIF's symbol table search routine, -FIND. Of
\r
352 course, XVOC could be moved to VOCABULARY, where it belongs, (and might
\r
353 also be changed to a DOES> definition, but I don't think that's
\r
354 necessary on the 6809).
\r
357 *******************************************************************************
\r
358 The BIF Symbols/Definitions/Routines
\r
361 I have added slightly to the FORTH documentation methods. I also show
\r
362 the results on the return stack and in the input buffer, where
\r
363 appropriate. The name on the left is the definition name, as it will be
\r
364 found by ' (TICK) and the outer interpreter. To the right I indicate
\r
365 precedence (P for higher Precedence than definition) and restrictions (C
\r
366 for Compile-only). Below the name, I indicate the assembler source
\r
367 label, where it is different from the name. The definitions on the
\r
368 SCREENS disk also indicate screen and sector for the source.
\r
370 The parameters attempt to be mnemonic. It will help to remember that
\r
371 there are no stack items smaller than 16 bits; character and byte
\r
372 parameters will be integers with their high-bytes ignored. Double
\r
373 integers are 32 bits. A further reminder, parameters are listed Pascal
\r
374 order, first pushed first; thus, the right-most is at the top of stack,
\r
375 or the lowest address. I specify a list of doubles pushed onto the
\r
376 stack (used in the assembler) as dl. Finally, I will try to mean 16-bit
\r
377 integer when I say word, but I may sometimes slip and mean (per FORTH
\r
378 jargon) a definition/routine.
\r
380 Flags are slightly different than fig-FORTH -- true is set as -1, sensed
\r
381 as non-zero. False is zero, of course.
\r
383 A number of routines (such as ENCLOSE) accept and return different
\r
384 parameters than specified in fig-FORTH. I assume that those for whom
\r
385 this fact may be of consequence will have copies of the standard and can
\r
386 compare at their leisure.
\r
388 The definitions are not alphabetized, nor are they listed in order of
\r
389 immediate interest, but they are organized by the source file they occur
\r
390 in. The following file descriptions are generally accurate, but some
\r
391 code is out of place.
\r
393 BIF contains most of the virtual machine.
\r
395 BIF.M contains the inner interpreter macro, some important
\r
396 symbol table offsets, and a few other general EQUates and
\r
399 BIFDP contains the rest of the virtual machine.
\r
401 BIFU contains the allocation of the per-user system variables.
\r
403 BIFST contains the boot up code and definitions.
\r
405 BIF1 contains most of the calculator-style expression evaluator.
\r
407 BIF2 is mostly constants and system variables, but contains the
\r
408 memory management primitives.
\r
410 Most of BIF3 is code which interacts with system variables, for
\r
411 example, the words which set the conversion base to sixteen,
\r
414 BIF4 contains multiplication and division, and the disk
\r
415 interface primitives.
\r
417 BIF5 is mostly output formatting.
\r
419 BIF6 is mostly input formatting and terminal interface.
\r
421 BIF7 contains most of the dictionary (interactive symbol table)
\r
424 Unless otherwise noted, all definitions are in the BIF vocabulary.
\r
426 There is much that is not sacred about FORTH and its dialects. For
\r
427 many, the attraction of FORTH is the great abandon with which one may
\r
428 play games with its inner workings. I have taken a number of liberties
\r
429 and these routines still function. If you have an idea, back your disks
\r
433 **** Definitions/Routines in BIF.ASM and BIFB.A:
\r
436 FETCH Replace address on stack with the word at the address.
\r
440 STORE Store second word on stack at address on top of stack.
\r
443 Push the following word from the instruction stream as a
\r
444 literal, or immediate value.
\r
447 Push a double integer literal (see LIT).
\r
450 { bifc_vm.c bif.asm
\r
451 EXECUTE ( adr --- ) C
\r
452 EXEC Jump to address on stack. Used by the "outer" interpreter to
\r
453 interactively invoke routines. (Not compile-only in fig.)
\r
455 0BRANCH ( f --- ) C
\r
456 ZBR BRANCH if flag is zero.
\r
458 1BRANCH ( f --- ) C
\r
459 TBR BRANCH if not zero. Not as useful as it might appear.
\r
462 Add the following word from the instruction stream to the
\r
463 instruction pointer (Y++). Causes a program branch.
\r
466 (LOOP) ( --- ) ( limit index *** limit index+1) C
\r
467 XLOOP ( limit index *** )
\r
468 Counting loop primitive. The counter and limit are the top two
\r
469 words on the return stack. If the updated index/counter does
\r
470 not exceed the limit, a branch occurs. If it does, the branch
\r
471 does not occur, and the index and limit are dropped from the
\r
474 (+LOOP) ( n --- ) ( limit index *** limit index+n ) C
\r
475 XPLOOP ( limit index *** )
\r
476 Loop with a variable increment. Terminates when the index
\r
477 crosses the boundary from one below the limit to the limit. A
\r
478 positive n will cause termination if the result index equals the
\r
479 limit. A negative n must cause the index to become less than
\r
480 the limit to cause loop termination.
\r
482 (DO) ( limit index --- ) ( *** limit index )
\r
483 XDO Move the loop parameters to the return stack. Synonym for D>R.
\r
485 I ( --- index ) ( limit index *** limit index )
\r
486 Copy the loop index from the return stack. Synonym for R.
\r
488 J ( --- index2 ) ( index2 limit1 index1 *** index2 limit1 index1 )
\r
489 Copy the outer loop index from the return stack. As with (DO)
\r
490 and I, J may be useful outside looping contexts.
\r
492 DIGIT ( c base --- ff )
\r
493 ( c base --- n tf )
\r
494 Translate C in base, yielding a translation valid flag. If the
\r
495 translation is not valid in the specified base, only the false
\r
498 (FIND) ( name vocptr --- locptr f )
\r
499 PFIND Search vocabulary for a symbol called name. Name is a pointer
\r
500 to a NUL terminated string of characters without count, vocptr
\r
501 is a pointer to a pointer to a definition (the length byte of a
\r
502 symbol table entry). Locptr is also a pointer to a pointer to a
\r
503 definition, such that, if the flag is false, a symbol with the
\r
504 name searched for may be inserted in proper order at that point.
\r
505 Vocptr and locptr may point to either the right or left entry of
\r
506 the order-parent entry in the symbol table, or to pointer to the
\r
507 root of a vocabulary. HIDDEN (smudged) definitions are
\r
508 lexically less than their name strings. Searches only the local
\r
509 vocabulary, from the order-parent node passed. Uses (REFIND).
\r
511 vocptr is a pointer to the parameter field of a vocabulary
\r
514 ENCLOSE ( buffer c --- s length )
\r
515 ENCLOS Scan buffer for a symbol delimited by c or ASCII NUL; return the
\r
516 length of the symbol scanned and the address of its first
\r
517 character. A length 0 and a pointer to a NUL means no symbol
\r
518 was scanned before NUL terminator was reached. (Buffer is the
\r
519 address of the buffer array to scan.)
\r
521 LITERAL ( n --- ) P
\r
522 LITER ( n --- n ) if interpreting.
\r
523 Compile n as a literal, if compiling.
\r
525 DLITERAL ( d --- ) P
\r
526 DLITER ( d --- d ) if interpreting.
\r
527 Compile d as a double literal, if compiling.
\r
530 Write c to the output device (screen or printer). Uses the ECB
\r
531 device number at address $6F, -2 is printer, 0 is screen.
\r
535 Wait for a key from the keyboard. If the key is BREAK, set the
\r
536 high byte (result $FF03).
\r
538 ?TERMINAL ( --- f )
\r
539 QTERM Scan keyboard, but do not wait. Return 0 if no key, BREAK
\r
540 ($ff03) if BREAK is pressed, or key currently pressed.
\r
543 EMIT a Carriage Return (ASCII CR).
\r
545 (;CODE) ( --- ) ( IP *** ) C
\r
546 XSCODE Compile the latest symbol as a reference to a ;CODE definition;
\r
547 overwrite the first three (3!) bytes of the code field of the
\r
548 symbol found by LATEST with a jump to the low-level
\r
549 characteristic code provided in the defining definition, and pop
\r
550 IP. The machine-level code which follows (;CODE) in the
\r
551 instruction stream is not executed by the defining symbol, but
\r
552 becomes the characteristic of the defined symbol. This is the
\r
553 usual way to generate the characteristics of VARIABLEs,
\r
554 CONSTANTs, etc., when FORTH compiles itself. BIF, however, was
\r
555 hand-optimized to take advantage of direct-page jumps. So its
\r
556 pre-compiled defining symbols with low-level characteristics
\r
557 look different from those compiled by BIF, having two bytes in
\r
558 their code fields instead of three.
\r
561 TOPRT Send output to printer via CoCo's ROM routines and the device
\r
562 number variable (see EMIT).
\r
565 TOVID Send output to CRT, converse of >PRT.
\r
568 LSHIFT Fast multiply by two.
\r
571 RSHIFT Fast divide by two.
\r
573 (REFIND) ( name vocptr --- name locptr f )
\r
574 PREF Search vocabulary for the first symbol called name. (Will find
\r
575 HIDDEN/SMUDGEd definitions.) Name is a pointer to a string of
\r
576 characters without count, vocptr is a pointer to a pointer to a
\r
577 definition (the length byte of a symbol table entry). Locptr is
\r
578 also a pointer to a pointer to a definition, such that, if the
\r
579 pointer at the pointer is NULL, a symbol with the name searched
\r
580 for may be inserted in proper order at that point. Vocptr and
\r
581 locptr may be either the right or left entry of the order-parent
\r
582 entry in the symbol table, or a pointer to the root of a
\r
583 vocabulary. Flag f will indicate by offset whether the child or
\r
584 empty slot is a left link (LFTOFF), right link (RTOFF), or
\r
585 vocabulary (PFAOFF).
\r
587 vocptr is a pointer to the parameter field of a vocabulary
\r
591 **** Definitions/Routines in BIF1.A and BIF1B.A:
\r
593 MOVE ( source target count --- )
\r
594 Copy/move count words from source to target. Moves ascending
\r
595 addresses, so that overlapping only works if the source is
\r
596 above the destination.
\r
598 CMOVE ( source target count --- )
\r
599 Copy/move count bytes from source to target. Moves ascending
\r
600 addresses, so that overlapping only works if the source is
\r
601 above the destination.
\r
603 U* ( u1 u2 --- ud )
\r
604 USTAR Multiplies the top two unsigned integers, yielding a double
\r
607 U/ ( ud u --- uremainder uquotient )
\r
608 USLASH Divides the top unsigned integer into the second and third words
\r
609 on the stack as a single unsigned double integer, leaving the
\r
610 remainder and quotient (quotient on top) as unsigned integers.
\r
612 The smaller the divisor, the more likely dropping the high word
\r
613 of the quotient loses significant bits.
\r
615 AND ( n1 n2 --- n )
\r
616 Bitwise and the top two integers.
\r
621 XOR ( n1 n2 --- n )
\r
622 Bitwise exclusive or.
\r
625 SPFEH Fetch the parameter stack pointer (before it is pushed).
\r
627 SP! ( whatever --- nothing )
\r
628 SPSTO Initialize the parameter stack pointer from the USER variable
\r
629 S0. Effectively clears the stack.
\r
631 RP! ( whatever *** nothing )
\r
632 RPSTO Initialize the return stack pointer from the USER variable R0.
\r
633 Effectively aborts all in process definitions, except the active
\r
634 one. An emergency measure, to be sure.
\r
637 SEMIS Pop IP from return stack (return from high-level definition).
\r
638 Can be used in a screen to force interpretion to terminate.
\r
640 LEAVE ( limit index *** index index )
\r
641 Force the terminating condition for the innermost loop by
\r
642 copying its index to its limit. Termination is postponed until
\r
643 the next LOOP or +LOOP instruction is executed. The index
\r
644 remains available for use until the LOOP or +LOOP instruction is
\r
647 >R ( n --- ) ( *** n ) C
\r
648 TOR Move top of parameter stack to top of return stack.
\r
650 R> ( --- n ) (n *** ) C
\r
651 RFROM Move top of return stack to top of parameter stack.
\r
653 R ( --- n ) ( n *** n )
\r
654 Copy the top of return stack to top of parameter stack. A
\r
657 = ( n1 n2 --- n1=n2 )
\r
658 EQ Flag true if n1 and n2 are equal, otherwise false.
\r
660 < ( n1 n2 --- n1<n2 )
\r
661 LT Flag true if n1 is less than n2, otherwise false.
\r
664 ZEQ Logically invert top of stack; or flag true if top is zero,
\r
668 ZLESS Flag true if top is negative (MSbit set), otherwise false.
\r
670 > ( n1 n2 --- n1>n2 )
\r
671 GT Flag true if n1 is greater than n2, false otherwise.
\r
674 + ( n1 n2 --- n1+n2 )
\r
675 ADD Add top two words.
\r
677 - ( n1 n2 --- n1-n2 )
\r
678 SUB Subtract top two words.
\r
681 D+ ( d1 d2 --- d1+d2 )
\r
682 DADD Add top two double integers.
\r
684 D- ( d1 d2 --- d1-d2 )
\r
685 DSUB Subtract top two double integers.
\r
688 Negate (two's complement) top of stack.
\r
690 DMINUS ( d --- -d )
\r
691 Negate (two's complement) top two words on stack as a double
\r
694 OVER ( n1 n2 --- n1 n2 n1 )
\r
695 Push a copy of the second word on stack.
\r
698 Discard the top word on stack.
\r
700 SWAP ( n1 n2 --- n2 n1 )
\r
701 Swap the top two words on stack.
\r
703 DUP ( n1 --- n1 n1 )
\r
704 Push a copy of the top word on stack.
\r
707 ADDSTO Add the second word on stack to the word at the adr on top of
\r
710 TOGGLE ( adr b --- )
\r
711 TOG Exclusive or byte at adr with low byte of top word.
\r
714 CFEH Replace address on top of stack with the byte at the address.
\r
715 High byte of result is clear.
\r
718 CSTO Store low byte of second word on stack at address on top of
\r
719 stack. High byte is ignored.
\r
721 ROT ( n1 n2 n3 --- n2 n3 n1 )
\r
722 Rotate the top three words on stack, bringing the third word to
\r
726 Calculate a back reference from HERE and compile it. The result
\r
727 compiled is adr-HERE-2, being adjusted for post-increment
\r
731 Bit (one's) complement the top of stack.
\r
733 ' ( --- ) compiling P
\r
734 TICK ( --- adr ) interpreting
\r
736 Parse a symbol name from input and search, -DFIND, the
\r
737 dictionary for it; compile the address as a literal if
\r
738 compiling, otherwise just push it. Recursively searches parent
\r
739 vocabularies, aborts if the parsed symbol name is not found.
\r
742 NEXSCR Continue interpreting source code on the next screen.
\r
744 1ARRAY ( start end size --- )
\r
745 ONEARR { 1ARRAY name } input
\r
746 Parse name and compile it as a linear array of size elements
\r
747 from start index to end index inclusive. The number of bytes in
\r
748 the array is (end-start+1)*size. The 1ARRAY characteristic is a
\r
749 direct page routine.
\r
752 UTIL The UTILITIES vocabulary.
\r
754 DP@ ( --- adr ) in UTILITIES
\r
755 DPFEH Calculate and push the address of the direct page.
\r
757 DCONSTANT ( d --- )
\r
758 DCON { DCONSTANT name } input
\r
759 Parse name and compile it as a double constant with a value of
\r
760 d. The DCONSTANT characteristic is a direct page routine.
\r
763 Swap the bytes of the top word on stack.
\r
766 Swap the nibbles of the top word on stack. The low-level code
\r
767 looks funny, but it was the fastest way I could think up.
\r
770 **** Definitions/Routines in BIF2.A and BIF2B.A:
\r
772 Increments and decrements for top of stack:
\r
773 1+ ADD1 ( n --- n+1 )
\r
774 1- SUB1 ( n --- n-1 )
\r
775 2+ ADD2 ( n --- n+2 )
\r
776 2- SUB2 ( n --- n-2 )
\r
784 BL BL ( --- SP ) ASCII SPACE character
\r
785 C/L CPERL ( --- 32 ) The number of columns per line on the
\r
786 CRT. Determines the length of error messages and the
\r
787 width and length of screen listings, among other things.
\r
788 FIRST ( --- adr ) The base of the disk buffer space.
\r
789 LIMIT ( --- adr ) The limit of the disk buffer space.
\r
790 B/BUF BPBUF ( --- 256 ) The size, in bytes, of a buffer.
\r
791 B/SCR BPSCR ( --- 4 ) The size, in buffers, of a screen.
\r
793 +ORIGIN ( n --- adr )
\r
794 PORIG Calculate the address of the (n/2)th entry in the boot-up
\r
795 parameter table. (Adds the base of the boot-up table to n.)
\r
798 TIB ( --- vadr ) Terminal Input Buffer address. Note
\r
799 that is a variable, so users may allocate their own
\r
800 buffers, but it must be @ed.
\r
801 WARNING WARN ( --- vadr ) Availability of error messages on disk.
\r
802 Contains 1 if messages available, 0 if not, -1 if a disk
\r
803 error has occurred.
\r
804 In bif-c, add 2 for internal error strings.
\r
805 FENCE ( --- vadr ) Boundary for FORGET.
\r
806 DP DPC ( --- vadr ) Dictionary pointer, fetched by HERE.
\r
807 ROOT ( --- vadr ) Current local/context interpretation
\r
808 vocabulary root. Not a fig variable.
\r
809 BLK ( --- vadr ) Block being interpreted. Zero refers to
\r
811 IN ( --- vadr ) Input buffer offset/cursor.
\r
812 OUT ( --- vadr ) Output buffer offset/cursor.
\r
813 SCR ( --- vadr ) Screen being edited. Unused in BIF.
\r
814 OFFSET ( --- vadr ) Sector offset for LOADing screens, set
\r
815 by DRIVE to make a new drive the default.
\r
816 STATE ( --- vadr ) Compiler/interpreter state.
\r
817 BASE ( --- vadr ) Numeric conversion base.
\r
818 DPL ( --- vadr ) Output decimal point locator.
\r
819 FLD ( --- vadr ) Field width for I/O formatting.
\r
820 CSP ( --- vadr ) Compiler stack mark for stack check.
\r
821 R# RNUM ( --- vadr ) Editing cursor location. Unused in BIF.
\r
822 HLD ( --- vadr ) Pointer to last HELD character in PAD.
\r
823 FOREWARD FORE ( --- vadr ) Pointer to earliest definition in active
\r
824 forward block. Not fig.
\r
825 CURRENT CURR ( --- vadr ) NFA of LATEST definition. Not fig.
\r
826 PREV ( --- vadr ) Most Recently Used buffer.
\r
827 USE ( --- vadr ) Least Recently Used buffer.
\r
828 DROOT ( --- vadr ) Current defining/compiling vocabulary
\r
832 Get contents of DP, with heap/stack overflow ERROR check. More
\r
833 than a pseudo-constant.
\r
836 Increase heap (add n to DP), ERROR check stack/heap.
\r
839 COMMA Store word n at DP++, ERROR check stack/heap.
\r
842 CCOMMA Store byte b at DP+, ERROR check stack/heap.
\r
852 QCST Push compile/interpret state bits.
\r
854 IF ( --- cdptr $4946 ) P,C
\r
855 Compile a 0BRANCH and dummy offset and push IF reference to fill
\r
856 in and IF control construct flag.
\r
858 ELSE ( cdptr1 $4946 --- cdptr2 $4946 ) P,C
\r
859 ERROR check IF flag, compile BRANCH with dummy offset, resolve
\r
860 IF reference (FILL-IN offset-2 to HERE at cdptr1), and leave
\r
861 reference to BRANCH for ELSE.
\r
864 ENDIF ( cdptr $4946 --- ) P,C
\r
865 ERROR check IF flag, resolve IF reference (FILL-IN offset-2 to
\r
866 HERE at cdptr) and pop reference/flag.
\r
869 **** Definitions/Routines in BIF3.A and BIF3B.A:
\r
871 LATEST ( --- symptr )
\r
872 Fetch CURRENT as a per-USER constant.
\r
874 Symbol table conversions:
\r
875 LFA ( n --- n+LFAOFF ) Convert NFA (not PFA) to LFA.
\r
876 --> Convert header address to LFA.
\r
877 CFA ( n --- n+CFAOFF ) Convert NFA (not PFA) to CFA.
\r
878 --> Convert header address to CFA.
\r
879 GFA ( n --- n+GFAOFF ) Convert NFA (not PFA) to CFA.
\r
880 --> Convert header address to GFA.
\r
881 PFA ( n --- n+PFAOFF ) Convert NFA to PFA.
\r
882 --> Convert header address to PFA.
\r
883 NFA ( n --- n-PFAOFF ) Convert PFA to NFA.
\r
884 --> Convert PFA to header address.
\r
885 NFA is the address of the length byte in a symbol table header.
\r
886 --> Now we use the header address instead of the NFA.
\r
887 PFA is the address at which a high-level definition's icode list
\r
888 begins, or a variable's, constant's, or vocabulary's value is
\r
890 CFA is where a definition's code begins, or where the jump to
\r
891 its characteristic is stored.
\r
892 LFA is the address of a definition's allocation link.
\r
893 GFA is the address of a definition's vocabulary link.
\r
896 STOCSP Save the parameter stack pointer in CSP for compiler checks.
\r
898 Set the conversion base:
\r
899 HEX ( --- ) Sixteen.
\r
900 DECIMAL DEC ( --- ) Ten.
\r
901 OCTAL OCT ( --- ) Eight.
\r
903 FILL ( adr n b --- )
\r
904 Fill n bytes at adr with b.
\r
906 ERASE ( adr n --- )
\r
907 Fill n bytes with 0.
\r
909 BLANKS ( adr n --- )
\r
910 Fill n bytes with ASCII SPACE.
\r
913 Format a character at the left of the HLD output buffer.
\r
916 Give the address of the output PAD buffer. Not same as fig. PAD
\r
917 points to the end of a 34 byte buffer for numeric conversion.
\r
920 STOD Sign extend n0 to a double integer.
\r
922 +- ( n0 n1>=0 --- n0 )
\r
923 CHS ( n0 n1<0 --- -n0 )
\r
924 Change sign of second iff top is negative.
\r
926 D+- ( d0 n0>=0 --- d0 )
\r
927 DCHS ( d0 n0<0 --- -d0 )
\r
928 Change sign of second and third as double iff top is negative.
\r
932 Change the top of stack to its absolute value.
\r
934 DABS ( d>=0 --- d )
\r
936 Change the top double to its absolute value.
\r
938 MIN ( n0 n1 --- min(n0,n1) )
\r
939 Leave the minimum of the top two integers.
\r
941 MAX ( n0 n1 --- max(n0,n1) )
\r
942 Leave the maximum of the top two integers.
\r
945 LBRAK Clear the compile state bits (shift to interpret).
\r
948 RBRAK Set the compile state bits (shift to compile).
\r
951 IMMED Toggle precedence bit of LATEST definition header. During
\r
952 compiling, most symbols scanned are compiled. IMMEDIATE
\r
953 definitions execute whenever the outer INTERPRETer scans them,
\r
954 but may be compiled via ' (TICK).
\r
957 Toggle HIDDEN bit of LATEST definition header, to hide it until
\r
958 defined or reveal it after definition.
\r
960 COMPILE-ONLY ( --- )
\r
961 COMPO Toggle compile only bit of LATEST definition header.
\r
963 COUNT ( strptr --- strptr+1 count )
\r
964 Convert counted string to string and count. (Fetch the byte at
\r
965 strptr, post-increment.)
\r
967 -TRAILING ( strptr count1 --- strptr count2 )
\r
968 DTRAIL Supress trailing blanks (subtract count of trailing blanks from
\r
971 (MACHINE) ( ip *** ) C
\r
972 XMACH Change from executing icodes to machine code in a definition by
\r
973 saving IP and jumping to it after popping the old IP.
\r
975 TYPE ( strptr count --- )
\r
976 EMIT count characters at strptr.
\r
978 CTS-TYPE ( adr --- ) in UTILITIES (bif-c)
\r
979 CTD_TYPE TYPE the (byte) counted string at adr.
\r
982 XDOTQ TYPE counted string out of instruction stream (updating IP).
\r
985 IDDOT Print definition's name from its NFA.
\r
987 FILL-IN ( cdptr --- ) C
\r
988 FILLIN Resolve the reference at cdptr by writing the offset from
\r
989 cdptr+2 to HERE at cdptr. Offset is adjusted for post-increment
\r
992 BEGIN ( --- cdptr $4245 ) P,C
\r
993 Push HERE for BACK reference for general (non-counting) loops,
\r
994 with BEGIN construct flag.
\r
996 AGAIN ( cdptr $4245 --- ) P,C
\r
997 ERROR check BEGIN flag, compile BRANCH and BACK resolve it to
\r
1000 UNTIL ( cdptr $4245 --- ) P,C
\r
1001 ERROR check BEGIN flag, compile 0BRANCH and BACK resolve it to
\r
1004 WHILE ( $4245 --- $4245 cdptr $5748 ) P,C
\r
1005 ERROR check BEGIN flag, compile 0BRANCH with dummy offset, push
\r
1006 WHILE reference -- HERE -- /flag on top of BEGIN reference/flag.
\r
1008 REPEAT ( cdptr1 $4245 cdptr2 $5748 --- ) P,C
\r
1009 ERROR check WHILE and BEGIN flags, compile BRANCH and BACK fill
\r
1010 cdptr1 reference, FILL-IN 0BRANCH reference at cdptr2.
\r
1012 DO ( --- cdptr $444F ) P,C
\r
1013 Compile (DO), push HERE for BACK refenece, and push DO control
\r
1017 **** Definitions/Routines in BIF4.A and BIF4B.A:
\r
1019 M* ( n1 n2 --- d )
\r
1020 MSTAR Multiply top two words as signed integers with a signed double
\r
1023 M/ ( d n --- remainder quotient )
\r
1024 MSLASH Divide signed double dividend d (2nd & 3rd words) by signed
\r
1025 word divisor n (top) yielding signed word remainder and quotient.
\r
1026 Quotient is top, remainder takes sign of dividend.
\r
1028 Thus, dividend == quotient * divisor + remainder
\r
1029 with truncating toward zero.
\r
1030 This can overflow in quotient.
\r
1032 * ( multiplier multiplicand --- product )
\r
1033 STAR Signed word multiply.
\r
1035 /MOD ( dividend divisor --- remainder quotient )
\r
1036 SLAMOD M/ in word-only form, i. e., signed division of 2nd word by top
\r
1037 word yielding signed word quotient and remainder.
\r
1039 / ( dividend divisor --- quotient )
\r
1040 SLASH Signed word divide without remainder.
\r
1042 MOD ( dividend divisor --- remainder )
\r
1043 Remainder function, result takes sign of dividend.
\r
1045 */MOD ( multiplier multiplicand divisor --- remainder quotient )
\r
1046 SSMOD Signed precise division of product: multiply 2nd and 3rd
\r
1047 words on stack and divide the 31-bit product by the top word,
\r
1048 leaving both quotient and remainder. Remainder takes sign of
\r
1049 product. Guaranteed not to lose significant bits.
\r
1051 */ ( multiplier multiplicand divisor --- quotient )
\r
1052 STARSL */MOD without remainder.
\r
1054 M/MOD ( ud1 u1 --- u2 ud2 )
\r
1055 MSMOD U/ with an (unsigned) double quotient. Guaranteed not to lose
\r
1056 significant bits, if you are prepared to deal with them.
\r
1058 +BUF ( buffer1 --- buffer2 f )
\r
1059 ADDBUF Bump to next buffer, flag false if result is PREVious buffer,
\r
1060 otherwise flag true. Used in the LRU allocation routines.
\r
1063 Mark PREVious buffer dirty, in need of being written out.
\r
1065 EMPTY-BUFFERS ( --- )
\r
1066 EMTBUF Mark all buffers empty. Standard method of discarding changes.
\r
1068 DRIVE-OFFSET ( n --- eadr )
\r
1069 DROFFS 1ARRAY of drive offsets (see DO1ARR in the description of the
\r
1070 virtual machine). Contains the size, in sectors, of four
\r
1071 drives, plus a fifth entry to end the table if all four drives
\r
1072 are defined. To make drive 2 a 40 track SS-DD drive:
\r
1073 40 18 * 2 DRIVE-OFFSET !
\r
1074 (Formatting the extra tracks can be handled with OS-9.)
\r
1077 Add up the sector offset to sector 0 of drive n and store it in
\r
1078 OFFSET. This changes the logically lowest drive for LOADING.
\r
1080 R/W ( buffer sector f --- )
\r
1081 RW Read or Write the specified (absolute -- ignores OFFSET) sector
\r
1082 from or to the specified buffer. A zero flag specifies write,
\r
1083 non-zero specifies read. Sector is an unsigned integer, buffer
\r
1084 is the buffer's address. Uses the CoCo ROM disk routines. This
\r
1085 is where you would want to handle double-sided drives.
\r
1087 ?ERROR ( 0 n --- ) ( *** )
\r
1088 QERROR ( true n --- IN BLK ) ( anything *** nothing )
\r
1089 If flag is false, do nothing. If flag is true, issue error
\r
1090 MESSAGE and QUIT or ABORT, via ERROR. Leaves cursor position
\r
1091 (IN) and currently loading block number (BLK) on stack, for
\r
1094 ?COMP ( --- ) ( *** )
\r
1095 QCOMP ( --- IN BLK ) ( anything *** nothing )
\r
1096 ERROR if not compiling.
\r
1098 ?EXEC ( --- ) ( *** )
\r
1099 QEXEC ( --- IN BLK ) ( anything *** nothing )
\r
1100 ERROR if not executing.
\r
1102 ?PAIRS ( n1 n2 --- ) ( *** )
\r
1103 QPAIRS ( n1 n2 --- IN BLK ) ( anything *** nothing )
\r
1104 ERROR if n1 and n2 are unequal. MESSAGE says compiled
\r
1105 conditionals do not match.
\r
1107 ?CSP ( --- ) ( *** )
\r
1108 QCSP ( --- IN BLK ) ( anything *** nothing )
\r
1109 ERROR if return/control stack is not at same level as last !CSP.
\r
1110 Used to indicate that a definition has been left incomplete.
\r
1111 *** Actually, this checks the parameter stack. ***
\r
1113 ?LOADING ( --- ) ( *** )
\r
1114 QLOAD ( --- IN BLK ) ( anything *** nothing )
\r
1115 ERROR if not loading, i. e., if BLK is non-zero. [correction: if BLK _is_ zero!]
\r
1118 COMP Compile an in-line literal value from the instruction stream.
\r
1120 LOOP ( cdptr $444f --- ) P,C
\r
1121 ERROR check DO flag, compile (LOOP), fill in BACK reference.
\r
1123 +LOOP ( cdptr $444f --- ) P,C
\r
1124 PLOOP ERROR check DO flag, compile (+LOOP), fill in BACK reference.
\r
1127 Begin interpretation of screen (block) n. See also NEXSRC,
\r
1128 SEMIS, and ***NULLL****GGGGGHHHHTHNiTHNiTHNi
\r
1131 BUILDS Build a header for DOES> definitions. Actually just compiles a
\r
1132 CONSTANT zero which can be overwritten later by DOES>. Note
\r
1133 that <BUILDS is not IMMEDIATE, and therefore executes during a
\r
1134 definition's run-time, rather than its compile-time. It is not
\r
1135 intended to be used directly, but rather so that one definition
\r
1136 can build another. Also, note that nothing particularly special
\r
1137 happens in the defining definition until DOES> executes. The
\r
1138 name <BUILDS is intended to be a reminder of what is about to
\r
1141 DOES> ( --- ) ( IP *** ) C
\r
1142 DOES Define run-time behavior of definitions compiled/defined by a
\r
1143 high-level defining definition -- the FORTH equivalent of a
\r
1144 compiler-compiler. DOES> assumes that the LATEST symbol table
\r
1145 entry has at least one word of parameter field, which <BUILDS
\r
1146 provides. Note that DOES> is also not IMMEDIATE. When the
\r
1147 defining word containing DOES> executes the DOES> icode, it
\r
1148 overwrites the LATEST symbol's CFA with jsr <XDOES, overwrites
\r
1149 the first word of that symbol's parameter field with its own IP,
\r
1150 and pops the previous IP from the return stack. The icodes which
\r
1151 follow DOES> in the stream do not execute at the defining word's
\r
1152 run-time. Examining XDOES in the virtual machine shows that the
\r
1153 defined word will execute those icodes which follow DOES> at its
\r
1154 own run-time. The advantage of this kind of behaviour, which
\r
1155 you will also note in ;CODE, is that the defined word can
\r
1156 contain both operations and data to be operated on. This is how
\r
1157 FORTH data objects define their own behavior. Finally, note
\r
1158 that the effective code field for DOES> definitions is four
\r
1162 SCODE ?CSP to see if there are loose ends in the defining definition
\r
1163 before shifting to the assembler, compile (;CODE) in
\r
1164 the defining definition's instruction stream, shift to
\r
1165 interpreting, make the ASSEMBLER vocabulary current, and !CSP to
\r
1166 mark the stack in preparation for assembling low-level code.
\r
1167 Note that ;CODE, unlike DOES>, is IMMEDIATE, and compiles
\r
1168 (;CODE),which will do the actual work of changing the LATEST
\r
1169 definition's characteristic when the defining word runs.
\r
1170 Assembly is done by the interpreter, rather than the compiler.
\r
1171 I could have avoided the anomalous three-byte code fields by
\r
1172 having ;CODE compile in the direct page jumps to the actual
\r
1173 low-level characteristics in the defining definition, thus
\r
1174 allowing (;CODE) to write a two-byte direct-page jumps into the
\r
1175 code fields of defined words. But that's a lot of work!
\r
1178 **** Definitions/Routines in BIF5.A and BIF5B.A:
\r
1182 IPCOM COMPILE a literal out of the instruction stream, without
\r
1183 checking compiler state. Used by the assembler to stuff
\r
1184 op-codes into the instruction stream, since the assembler runs
\r
1185 in interpretation mode.
\r
1187 ?STACK ( --- ) ( *** )
\r
1188 QSTACK ( --- IN BLK ) ( anything *** nothing )
\r
1189 ERROR if either stack out of bounds, or on evidence of stack
\r
1190 boundary problems. There is a word below the bottom of each
\r
1191 stack, which ABORT clears before it starts interpreting. In
\r
1192 addition to checking that both stacks have not overflowed, this
\r
1193 routine checks those two words, to see if underflow has
\r
1196 BUFFER ( n --- buffer )
\r
1197 Get a free buffer, assign it to block n, return buffer address.
\r
1198 Will free a buffer by writing it, if necessary. Does not
\r
1199 actually read the block. A bug in the fig LRU algorithm, which
\r
1200 I have not fixed, gives the PREVious buffer if USE gets set to
\r
1201 PREVious (the bug is that it happens). This bug sometimes
\r
1202 causes sector moves to become sector fills.
\r
1204 BLOCK ( n --- buffer )
\r
1205 Get BUFFER containing block n, relative to OFFSET. If block n
\r
1206 is not in a buffer, bring it in. Returns buffer address.
\r
1208 (LINE) ( line screen --- buffer C/L)
\r
1209 XLINE Bring in the sector containing the specified line of the
\r
1210 specified screen. Returns the buffer address and the width of
\r
1211 the screen. Screen number is relative to OFFSET. The line
\r
1212 number may be beyond screen 4, (LINE) will get the appropriate
\r
1215 .LINE ( line screen --- )
\r
1216 DOTLIN Print the line of the screen as found by (LINE), suppress
\r
1219 SPACES ( count --- )
\r
1220 EMIT count spaces, for non-zero, non-negative counts.
\r
1223 BEGHSH Initialize HLD for converting a double integer. Stores the PAD
\r
1226 #> ( d --- string length )
\r
1227 ENDHSH Terminate numeric conversion, drop the number being converted,
\r
1228 leave the address of the conversion string and the length, ready
\r
1231 SIGN ( n d --- d )
\r
1232 Put sign of n (as a flag) in front of the conversion string.
\r
1233 Drop the sign flag.
\r
1235 # ( d --- d/base )
\r
1236 HASH Generate next most significant digit in the conversion BASE,
\r
1237 putting the digit in front of the conversion string.
\r
1239 #S ( d --- dzero )
\r
1240 HASHS Convert d to a numeric string using # until the result is zero.
\r
1241 Leave the double result on the stack for #> to drop.
\r
1243 D.R ( d width --- )
\r
1244 DDOTR Print d on the output device in the current conversion base,
\r
1245 with sign, right aligned in a field at least width wide.
\r
1248 DDOT Print d on the output device in the current conversion base,
\r
1249 with sign, in free format with trailing space.
\r
1251 .R ( n width --- )
\r
1252 DOTR Print n on the output device in the current conversion base,
\r
1253 with sign, right aligned in a field at least width wide.
\r
1256 DOT Print n on the output device in the current conversion base,
\r
1257 with sign, in free format with trailing space.
\r
1260 QDOT Print signed word at adr, per DOT.
\r
1263 MESS If WARNING is 0, print "MESSAGE #n"; otherwise, print line n
\r
1264 relative to screen 4, the line number may be negative. Uses
\r
1265 .LINE, but counter-adjusts to be relative to the real drive 0.
\r
1267 In bif-c, add value of 2 for WARNING, for internal error message
\r
1270 (ABORT) ( anything --- nothing ) ( anything *** nothing )
\r
1271 IABORT An indirection for ABORT, for ERROR, which may be modified
\r
1274 ERROR ( anything line --- IN BLK ) ( anything *** nothing )
\r
1275 ( anything --- nothing ) ( anything *** nothing ) WARNING < 0
\r
1276 Prints out the last symbol scanned and MESSAGE number line. If
\r
1277 WARNING is less than zero, ABORTs through (ABORT), otherwise,
\r
1278 clears the parameter stack, pushes the INput cursor and
\r
1279 interpretaion BLK, and QUITs.
\r
1281 EDITOR ( --- ) in EDITOR P
\r
1282 Set the current interpretation vocabulary to EDITOR.
\r
1284 QSYNC ( --- ) in EDITOR
\r
1285 Synchronize the ECB cursor with R#.
\r
1287 EBLK ( --- vadr ) in EDITOR
\r
1288 USER variable containing the current editing block.
\r
1290 CURSOR ( --- adr ) in EDITOR
\r
1291 Calculates the address of the edit cursor, R#, within the
\r
1292 current editing block, bringing that block in if necessary.
\r
1294 QDUMP ( adr --- ) in EDITOR
\r
1295 Dump the 256 bytes at adr to the screen memory, at the top half
\r
1296 of the screen (bottom half of screen memory).
\r
1298 QARROW ( c --- c )
\r
1300 Adjust the cursor according to the key passed. If the key is a
\r
1301 cursor control key, return 0; otherwise, leave the key
\r
1302 unchanged. The regular back-arrow is used for cursor movement,
\r
1303 so the shifted back-arrow is used for destructive backspace.
\r
1304 Also, the up arrow is used for cursor movement, so caret is not
\r
1305 available without escaping. See QUICK.
\r
1308 **** Definitions/Routines in BIF6.A and BIF6B.A:
\r
1311 (NUMBER) ( d1 string --- d2 adr )
\r
1312 INUMB Convert the text at string into a number, accumulating the
\r
1313 result into d1, leaving adr pointing to the first character not
\r
1314 converted. If DPL is non-negative at entry, accumulates the
\r
1315 number of characters converted into DPL.
\r
1317 NUMBER ( ctstr --- d )
\r
1318 Convert text at ctstr to a double integer, taking the 0 ERROR if
\r
1319 the conversion is not valid. If a decimal point is present,
\r
1320 accumulate the count of digits to the decimal point's right into
\r
1321 DPL (negative DPL at exit indicates single precision). ctstr is
\r
1322 a counted string -- the first byte at ctstr is the length of the
\r
1323 string, but NUMBER ignores the count and expects a NUL
\r
1324 terminator instead.
\r
1326 WORDPAD ( --- vadr )
\r
1327 WORDPD The per-USER constant pointing to an intermediate
\r
1328 buffer for text scanning.
\r
1331 Scan a string terminated by the character c or ASCII NUL out of
\r
1332 input; store symbol at WORDPAD with leading count byte and
\r
1333 trailing ASCII NUL. Leading c are passed over, per ENCLOSE.
\r
1334 Scans from BLK, or from TIB if BLK is zero. May overwrite the
\r
1335 numeric conversion pad, if really long (length > 31) symbols are
\r
1339 The per-USER backspace constant.
\r
1341 EXPECT ( buffer n --- )
\r
1342 Get up to n-1 characters from the keyboard, storing at buffer
\r
1343 and echoing, with backspace editing, quitting when a CR is read.
\r
1344 Terminate it with a NUL.
\r
1347 EXPECT 128 (TWID) characters to TIB.
\r
1350 NUBLK End interpretation of a line or screen, and/or prepare for a new
\r
1351 block. Note that the name of this definition is an empty
\r
1352 string, so it matches on the terminating NUL in the terminal or
\r
1355 FIND ( namstr vocptr1 --- nfa vocptr2 )
\r
1356 Search a vocabulary, and its parents, if necessary, for a
\r
1357 definition called namstr. namstr is a counted (leading count
\r
1358 byte is ignored) string, vocptr1 is a pointer to a pointer to
\r
1359 a vocabulary tree or subtree. It will usually be the address of
\r
1360 the per-USER variable ROOT or DROOT, but may be a pointer to a
\r
1361 left or right link of an entry in the symbol tree. nfa will be
\r
1362 the name field address of the definition found, or a NULL.
\r
1363 vocptr2 will be the pointer-pointer to the last vocabulary
\r
1364 searched. vocptr2 will be the last vocabulary searche. See
\r
1367 -DFIND ( --- nfa vocptr ) { -DFIND name } typical input
\r
1368 DDFIND Parse a word, then FIND, first in the definition vocabulary,
\r
1369 then in the CONTEXT (interpretation) vocabulary, if necessary.
\r
1370 Returns the address of the symbol table entry or a NULL, and the
\r
1371 last vocabulary searched, per FIND.
\r
1373 -IFIND ( --- nfa vocptr ) { -DFIND name } typical input
\r
1374 DIFIND Same as -DFIND, except search the CONTEXT vocabulary first.
\r
1376 NAME, ( --- ctStrPtr length )
\r
1377 NCOMMA Store counted string at WORDPAD into dictionary, return HERE
\r
1378 pointer and length of string. Note that the count is not stored
\r
1379 in the dictionary, but that the address returned will be the
\r
1380 address to store the count at. (The length of the names of
\r
1381 definitions are stored after the actual names in the dictionary!)
\r
1383 But in BIF-C, the lengths are stored with the strings, and the
\r
1384 address returned points to where the counted string was stored.
\r
1387 FOREMK Set forward reference bit in LATEST definition, if FOREWARD is
\r
1390 (INSTALL) ( nfa vocptr --- ) P
\r
1391 PINSTA Install the header at nfa into the specified vocabulary, hiding
\r
1392 (SMUDGEing) any existing definitions of the same name in that
\r
1393 vocabulary. In BIF-6809, vocptr was a pointer to the parameter
\r
1394 field of the vocabulary, and we follow that in BIF-C v. 0.
\r
1397 INULL Store 0 word at NULL pointer (address 0).
\r
1400 TNULL Set warning to -1 and jmp to ERROR if the word at address 0
\r
1401 (NULL pointer) is not 0.
\r
1403 QUICK ( n --- ) in EDITOR
\r
1404 Quick and dirty editor; edits sectors, not screens. See above
\r
1407 NODE. ( nfa --- flag )
\r
1408 NDOT ID. with some formatting, extra information useful for
\r
1409 debugging, and a keyboard pause/abort test. Returns flag less
\r
1410 than 0 if BREAK key was pressed.
\r
1412 VISIT ( defptr vocptr --- )
\r
1413 Scan vocabulary at vocptr in ascending order, performing
\r
1414 definition at defptr at every node. defptr is an nfa, vocptr is
\r
1415 the pfa of a vocabulary, per FIND and ROOT/DROOT. The
\r
1416 definition to be executed will have parameters of the same form
\r
1417 as NDOT, doing something at a symbol tree node and leaving a
\r
1418 termination flag. VISIT checks for stack overflow and watches
\r
1419 the termination flag between executions. The VISITing
\r
1420 definition may have other parameters, but if it changes the
\r
1421 stack pointer from execution to execution VISIT will complain.
\r
1424 Alphabetically list the definitions in the current vocabulary.
\r
1427 **** Definitions/Routines in BIF7.A and BIF7B.A:
\r
1430 CREATE ( --- ) { CREATE name } input
\r
1431 Parse a name (length < 32 characters) and create a header,
\r
1432 reporting first duplicate found in either the defining
\r
1433 vocabulary or the context (interpreting) vocabulary. (INSTALL)
\r
1434 the header in the local vocabulary.
\r
1436 CONSTANT ( n --- )
\r
1437 CONST { value CONSTANT name } typical input
\r
1438 CREATE a header, compile a call to XCON, compile the constant
\r
1441 VARIABLE ( init --- )
\r
1442 VAR { init VARIABLE name } typical input
\r
1443 CREATE a header, compile a call to XVAR, compile the initial
\r
1447 USER { uboffset USER name } typical input
\r
1448 CREATE a header, compile a call to XUSER, compile the unsigned
\r
1449 byte offset in the per-USER table. The USER is entirely
\r
1450 responsible for maintaining allocation!
\r
1453 COLON { : name sundry-activities ; } typical input
\r
1454 If executing, record the data stack mark in CSP, CREATE a
\r
1455 header, compile a call to XCOL, and set state to compile. (SCOMP
\r
1456 is defined in this file.) CONTEXT (interpretation) vocabulary
\r
1460 SEMI { : name sundry-activities ; } typical input
\r
1461 ERROR check data stack against mark in CSP, compile ;S, unSMUDGE
\r
1462 LATEST definition, and set state to interpretation.
\r
1465 DOTQ { ." something-to-be-printed " } typical input
\r
1466 Use WORD to parse to trailing quote, if compiling, compile XDOTQ
\r
1467 and string parsed, otherwise, TYPE string.
\r
1469 [COMPILE] ( --- ) P
\r
1470 BCOMP { [COMPILE] name } typical use
\r
1471 -DFIND next WORD and COMPILE it, literally; used to compile
\r
1472 immediate definitions.
\r
1475 INTERP Interpret or compile, according to STATE. Searches words parsed
\r
1476 in dictionary first, via -IFIND, then checks for valid NUMBER.
\r
1477 Pushes or COMPILEs double literal if NUMBER leaves DPL
\r
1478 non-negative. ERROR checks the stack via ?STACK before
\r
1479 returning to its caller. Sensitive to COMPILE-ONLY bit in
\r
1482 QUIT ( anything *** nothing )
\r
1483 Clear return stack. Then INTERPRET and, if not compiling,
\r
1484 prompt with OK, in infinite loop.
\r
1487 Makes BIF the current interpretation vocabulary.
\r
1489 ASSEMBLER ( --- ) P
\r
1490 ASMBLR Makes ASSEMBLER the current interpretation vocabulary. Might
\r
1491 ought not to be IMMEDIATE.
\r
1493 DEFINITIONS ( --- )
\r
1494 DEFS Makes the current interpretation vocabulary also the current
\r
1495 defining vocabulary.
\r
1497 ABORT ( anything --- nothing ) ( anything *** nothing )
\r
1498 Clear parameter stack, intialize the NULL vector, set STATE to
\r
1499 interpret and BASE to DECIMAL, return to input from terminal,
\r
1500 restore DRIVE OFFSET to 0, set interpret and define vocabularies
\r
1501 to BIF, print out "6809 BIF Vx.x", and finally, QUIT. Used to
\r
1502 force the system to a known state and return control to the
\r
1503 standard INTERPRETer.
\r
1505 VOCABULARY ( --- ) { VOCABULARY name } input
\r
1506 VOCAB Create a vocabulary entry with a NULL local pointer, linked by
\r
1507 the parent pointer to the current defining vocabulary. The
\r
1508 vocabulary parameter passed to the various searching routines is
\r
1509 usually a pointer to the parameter field of a vocabulary. That
\r
1510 way, the root is functionally identically to a left or right
\r
1511 link in a node or leaf, particularly for insertion.
\r
1514 PAREN Parse out a comment and toss it away. This is probably not
\r
1515 useful, but it leaves the first 32 characters in WORDPAD.
\r
1517 DAD ( nfa --- name linkadr flag )
\r
1518 Search the parent vocabulary of the definition at nfa for nfa,
\r
1519 returning the address of the first character of the definition's
\r
1520 name, a pointer to the left or right link which links the
\r
1521 definition in, and a flag indicating whether the definition is
\r
1522 linked left or right. ERROR if the definition can't be found.
\r
1523 The return parameters are appropriate for REPEALing the
\r
1527 Remove the CURRENT/LATEST definition from the dictionary, from
\r
1528 the vocabulary in which it is defined. Updates CURRENT, alsoe
\r
1529 updates DROOT or ROOT and clears FOREWARD, if appropriate. If
\r
1530 the CURRENT definition is in a closed forward block, repeals the
\r
1531 entire block, so that forward references aren't pointing to
\r
1534 Except that I never got that last part written and working. So
\r
1535 you have to do that by hand. It does clear FOREWARD if FOREWARD
\r
1536 is pointing to the REPEALed definition.
\r
1538 FORGET ( --- ) { FORGET name } input
\r
1539 Parse out name of definition to FORGET to, -DFIND it, then
\r
1540 REPEAL until it is removed from the dictionary. Will not FORGET
\r
1541 if definition is not found, if it is in a recursive block, or if
\r
1542 it is below FENCE; the ERROR message will include the offending
\r
1548 **** Definitions/Routines in BIFST.A
\r
1551 COLD COLD boot. Initializes the system variables, prunes the
\r
1552 dictionary of everything beyond the initial FENCE, then WARM
\r
1555 WARM Resets stack areas and per-USER variables, clears the buffers,
\r
1556 then yields control to BIF via ABORT.
\r
1560 Definitions on the SCREENs disk follow. The vocabulary names are
\r
1561 abbreviated here under the definition names, A for ASSEMBLER, B for BIF,
\r
1562 U for UTILITIES, ^a for ^asm-util.
\r
1565 Index to the screens disk.
\r
1568 Title page and copyright notice.
\r
1572 - Call the debugging monitor: SWI followed by a jmp [,y++], so
\r
1573 that BIF can be continued.
\r
1575 After screen 2 creates MON, it updates FENCE to protect MON from WARM
\r
1576 boots. Will load in the active vocabulary.
\r
1578 **** SCREENs 4 & 5
\r
1579 Error and other Messages:
\r
1580 0: number conversion/unknown definition, no message text.
\r
1581 1: DATA STACK UNDERFLOW
\r
1582 2: DICTIONARY FULL
\r
1583 3: ADDRESS RESOLUTION ERROR for control structures
\r
1584 4: HIDES DEFINITION IN some vocabulary
\r
1585 5: NULL VECTOR WRITTEN
\r
1586 6: DISC RANGE? disk sector number out of range
\r
1587 7: DATA STACK OVERFLOW
\r
1588 8: DISC ERROR! of some sort -- is your drive door closed?
\r
1589 9: CAN'T EXECUTE A NULL!
\r
1590 10: CONTROL STACK UNDERFLOW
\r
1591 11: CONTROL STACK OVERFLOW
\r
1592 12: ARRAY REFERENCE OUT OF BOUNDS
\r
1593 13: ARRAY DIMENSION NOT VALID
\r
1594 14: NO PROCEDURE TO ENTER
\r
1595 15: ( was register error message for assembler )
\r
1597 17: COMPILATION ONLY, USE IN DEFinition
\r
1598 18: EXECUTION ONLY do not use while compiling
\r
1599 19: CONDITIONALS NOT PAIRED where's your if/loop end statement?
\r
1600 20: DEFINITION INCOMPLETE often same as 18, but hit ;
\r
1601 21: IN PROTECTED DICTIONARY don't try to forget below FENCE.
\r
1602 22: USE ONLY WHEN LOADING
\r
1603 23: OFF CURRENT EDITING SCREEN an editor cursor problem
\r
1604 24: DECLARE VOCABULARY
\r
1605 25: DEFINITION NOT IN VOCABULARY
\r
1606 26: IN FORWARD BLOCK
\r
1607 27: ALLOCATION LIST CORRUPTED: LOST
\r
1608 28: CAN'T REDEFINE nul! You tried to CREATE something without a name.
\r
1609 29: NOT FORWARD REFERENCE
\r
1610 30: ( was message about IMMEDIATE )
\r
1613 33: HAS INCORRECT ADDRESS MODE for 6809
\r
1614 34: HAS INCORRECT INDEX MODE for 6809
\r
1615 35: OPERAND NOT REGISTER in 6809
\r
1616 36: HAS ILLEGAL IMMEDIATE for 6809
\r
1617 37: PC OFFSET MUST BE ABSOLUTE pc-relative addressing error
\r
1618 38: ACCUMULATOR OFFSET REQUIRED for indexing mode
\r
1619 39: ILLEGAL MEMORY INDIRECTION for 6809
\r
1620 40: ILLEGAL INDEX BASE for 6809
\r
1621 41: ILLEGAL TARGET SPECIFIED for 6809 addressing mode or register
\r
1622 42: CAN'T STACK ON SELF for push/pull, try other stack pointer
\r
1623 43: DUPLICATE IN LIST of operands
\r
1624 44: REGISTER NOT STACK trying to push on a non-stack register?
\r
1625 45: EMPTY REGISTER LIST best supply some registers
\r
1626 46: IMMEDIATE OPERAND REQUIRED for 6809
\r
1627 47: REQUIRES CONDITION for control operator
\r
1629 49: COMPILE-TIME STACK UNDERFLOW
\r
1630 50: COMPILE-TIME STACK OVERFLOW
\r
1634 BYTE-DUMP ( adr n --- )
\r
1635 U Dump n bytes to output device, right adjusted in 4 character
\r
1636 columns. Field width is not big enough if BASE is six or less.
\r
1638 DUMP ( adr n --- )
\r
1639 B Formatted dump to output device, with ASCII interpretation.
\r
1640 Hard coded to 4 bytes per line.
\r
1643 B QDUMP a block/sector and set the cursor to the middle of the
\r
1644 screen so the dump remains visible.
\r
1646 QINDEX ( start end --- )
\r
1647 B QLIST block/sectors from number start to end, inclusive.
\r
1650 U Calculate the number of terminal lines per disc screen at
\r
1651 run-time. Sixteen, at present.
\r
1653 ULIST ( n --- flag )
\r
1654 U List screen n, with line numbers in the current base, leave
\r
1655 BREAK key flag. Uses C/L, to automatically adjust for screen
\r
1656 width (if C/L is set), but you may not want to use this
\r
1657 definition if you set C/L to something besides 32 or 64.
\r
1662 B ULIST screen n, line numbers in decimal.
\r
1664 INDEX ( start end --- )
\r
1665 B Print comment lines (line 0, and line 1 if C/L < 41) of screens
\r
1666 from start to end.
\r
1669 B List a printer page full of screens to the printer, formatted by
\r
1670 C/L. Line and screen number are in current base. Lists the
\r
1671 group containing screen n, will print 2 screens if C/L is 32,
\r
1672 three if C/L is 64. (Two may not fit well.)
\r
1677 U Put the cursor at the (CoCo 2) CRT screen HOME position.
\r
1680 U Put the cursor 8 lines down the (CoCo 2) CRT screen.
\r
1683 B Clear the (CoCo 2) CRT screen.
\r
1685 CAN-UP ( adr -- adr )
\r
1686 U Clear the UPDATE bit (MSB) for the buffer whose block word is at
\r
1687 adr. The characters in the buffer should be stored at adr+2.
\r
1689 W-BUF ( adr --- adr )
\r
1690 U Write the characters at adr+2 to the sector specified at adr,
\r
1691 clear the UPDATE flag.
\r
1693 SAVE-BUF ( adr --- adr )
\r
1694 U W-BUF, if UPDATEd.
\r
1697 B Save the PREViously edited buffer, if it was UPDATEd.
\r
1699 SAVE-BUFFERS ( --- )
\r
1700 B Write all buffers flagged for UPDATE, clear UPDATE bits.
\r
1703 B Cancel UPDATE of PREViously edited buffer.
\r
1707 CANCEL-UPDATES ( --- )
\r
1708 B Cancel UPDATEs of all buffers.
\r
1711 B Re-edit PREVious buffer.
\r
1713 .BUF ( adr --- adr )
\r
1714 U Dump buffer characters at adr+2, showing the sector number
\r
1718 B Dump all buffers, with block number, per .BUF.
\r
1721 B Dump contents and block number of PREVious buffer, per .BUF.
\r
1724 B QUICK edit block n, showing the block number.
\r
1727 B QUICK edit the PREVious block.
\r
1731 QOPY ( src dest --- )
\r
1732 B Move content of block/sector src to block dest. BUG: Doesn't
\r
1733 copy if src is already in a buffer (problem with LRU).
\r
1735 COPY ( src dest --- )
\r
1736 B Copy SCREEN src to SCREEN dest. Uses QOPY, so you should
\r
1737 EMPTY-BUFFERS before using COPY.
\r
1739 QBACK ( start end --- )
\r
1740 B Copy blocks from start to end to the next higher disc, at the
\r
1741 same sector offset.
\r
1744 B Erase and then EDIT block n.
\r
1751 FORWARD ( --- ) { FORWARD name } input
\r
1752 B Compile a forward reference header: CREATE, set FOREWARD if not
\r
1753 already set, compile jmp to RES-ERROR, unSMUDGE header.
\r
1755 :RESOLVE ( --- ) { :RESOLVE name } input P
\r
1756 A If the characteristic of name is a jmp to RES-ERROR, make it
\r
1757 LATEST, re-SMUDGE it, change jmp address to HERE; if the header
\r
1758 of name is the base of the forward block, clear FOREWARD.
\r
1759 Forward blocks should end with the definition of the first
\r
1760 forward reference in the block, to maintain the block's
\r
1761 integrity. (However, the FOREWARD USER variable can be modified
\r
1762 by hand, if necessary.)
\r
1764 :RES ( --- ) { :RES name } input
\r
1765 B Do ASSEMBLER's resolve, then compile jmp <XCOL and switch state
\r
1769 B ; but SMUDGE LATEST one more time.
\r
1771 **** SCREEN 11 does not continue LOADing! ****
\r
1776 B Print 80 ASCII characters starting with '!'.
\r
1779 B PL until any key is hit.
\r
1782 B PT, but send the output to the printer.
\r
1786 SLIST ( start end --- )
\r
1787 - ULIST SCREENs to printer from start to end inclusive.
\r
1790 This contains some experimental stuff that I was using to test my a
\r
1791 Sardis Technologies disk controller.
\r
1796 B Convert the CFA on the stack to an nfa and ID. it.
\r
1798 NAMES ( adr n --- )
\r
1799 B NAME n icodes at adr. Naively interprets anything as an icode.
\r
1802 **** The assembler starts here! ****
\r
1805 A Vocabulary for assembler support stuff. (Note that the name is
\r
1806 in lower case and looks funny when editing until the cursor
\r
1809 DREG ( n --- ) { n DREG name } input -> compile-time
\r
1810 ^a ( --- d ) -> run-time
\r
1811 Define register double constants. Most significant word is
\r
1812 `RE', the index and operand encodings are masked into the least
\r
1815 xx ( --- d ) high word is HEX 5245
\r
1816 A The register double constants in hex:
\r
1817 D 52458B00 A 52458608 B 52458509 PC 52458C05
\r
1818 U 52454003 S 52456004 Y 52452002 X 52450001
\r
1819 CC 5245EF0A DP 5245EF0B
\r
1820 Example: DP A EXG is exg dp,a
\r
1823 A Suffix constant for immediate values. Becomes the high byte:
\r
1824 4 # A LD is lda #4
\r
1827 ^a DP register emulator for the assembler. A per-USER variable at
\r
1828 offset HEX 42, initialized to whatever the load-time DP is.
\r
1831 A Push the current DPREG value, as a constant. To use as an
\r
1832 absolute address, push a 0 or -1 after.
\r
1833 Example: DPR 7 + 0 JMP is jmp <7
\r
1836 A Set the DPREG value, masks the low byte of adr out.
\r
1841 ^a Compile an index byte b with signed, constant, byte or word
\r
1842 offset, n. Sets bit 0 in the index byte if it compiles a word
\r
1846 ^a Compile opcode u. Compiles 16 bits if high byte of u is
\r
1849 ABS, ( adr u1 u2 --- )
\r
1850 ^a Compile an absolute address mode (direct page or extended)
\r
1851 op-code u1, oring u2 into u1 before compiling if the address is
\r
1852 not in the direct page.
\r
1854 PCOFF ( adr n1 --- n2 flag )
\r
1855 ^a Generate a pc-relative offset n2 from adr, adjusted by n1 bytes
\r
1856 of op-code/index. Flags true if offset fit in a byte, false if
\r
1857 it required 16 bits.
\r
1859 ?ABS ( d --- adr flag )
\r
1860 ^a Convert high word of d to flag showing true if high word was 0
\r
1861 or -1, false otherwise. A 0 or -1 high word indicates an
\r
1862 absolute address as an operand.
\r
1863 Example: HEX .FF20 B OR is orb $FF20
\r
1866 ^a ERROR if d is not absolute mode operand. Calculate offset and
\r
1867 compile index byte b and offset.
\r
1871 Auto-indexing address mode double constants, in ASSEMBLER vocabulary:
\r
1872 -) ( --- 4155.0082 ) ,-r
\r
1873 )++ ( --- 4155.0081 ) ,r++
\r
1874 )+ ( --- 4155.0080 ) ,r+
\r
1875 --) ( --- 4155.0083 ) ,--r
\r
1876 Example: )++ X , D ST is std ,x++
\r
1878 MASK, ( b1 b2 --- )
\r
1879 ^a Compile the bit-or of the top two words's low bytes.
\r
1882 ^a Convert a register offset specified by u to its extension byte
\r
1883 representation, mask in the index register and indirection
\r
1884 specifier b, and compile the resulting index byte.
\r
1886 IXOFF, ( n b --- )
\r
1887 ^a Generate the appropriate index extension byte for the constant
\r
1888 offset n and indirection level specified, mask in the index
\r
1889 register and indirection specifier b, and compile both the
\r
1890 extension byte and the offset. Handles zero and 5-bit offsets.
\r
1893 ^a Compile a (completely specified) extended-indirect extension
\r
1894 byte b and the absolute address d.
\r
1899 ^a Compile an index mode address operand. n contains the index
\r
1900 register and indirection level encoding, d contains the offset
\r
1901 or auto-mode specification. Zero offset must be explicit. Does
\r
1902 not block out unsupported [,r+] and [,-r] modes.
\r
1905 A Convert indexable register d1 to index mode specifier d2.
\r
1906 Examples: 0. X , B OR is orb ,x
\r
1907 A X , JMP is jmp a,x
\r
1908 TABLE 0 PC , X LEA is leax table,pcr
\r
1911 A Convert indexable register, absolute address, or index operand
\r
1912 d1 to memory indirect operand. Note that this will NOT
\r
1913 interfere with comments.
\r
1914 Examples: TABLE 6 + 0 PC ) JMP is jmp [6,pcr]
\r
1915 )++ S ) JSR is jsr ,s++
\r
1919 ACCM ( n1 n2 n3 --- n4 )
\r
1920 ^a Convert op-code n1, register n2, and mask bits n3 to accumulator
\r
1921 encoded op-code n4. Used for encoding ACCM destination
\r
1924 UNARY ( u --- ) >--> compile-time
\r
1925 ^a { u UNARY name } input >-/
\r
1926 ( do dx --- ) indexed modes >-\
\r
1927 ( d --- ) non-indexed modes >--> run-time
\r
1928 Unary op-code compiler -- compiles an assembler of unary
\r
1929 op-codes with op-code (u) and name. Run-time parameters: d is
\r
1930 the destination register or address, dx is the index
\r
1931 mode/register, do is the offset/auto mode.
\r
1932 Examples: A NEG is nega
\r
1933 7. U , ROR is ror 7,u
\r
1935 REG ( d adr --- d u sz ) -- JSR
\r
1936 ^a ( d adr --- u sz )
\r
1937 Encode binary destination register d into op-code from table at
\r
1938 adr. Table format is primary (byte), highest (byte), secondary
\r
1939 (word) secondary (word) .... Leave op-code u and size sz (-1 is
\r
1940 word, 0 is byte) of register encoded. Helps to reduce the
\r
1941 complexity of the binary operators op-code map, see BINARY
\r
1942 concerning constructing the tables.
\r
1947 ^a Compile an immediate op-code u with immediate operand n of size
\r
1948 byte, if sz == 0, or word, ERROR if op-code is ST or JSR.
\r
1950 BINARY ( ul b ub --- ) >--> compile-time
\r
1951 ^a { ul b ub BINARY name } input >-/
\r
1952 ( ds --- ) JSR >-\
\r
1953 ( ds dd --- ) non-indexed mode >--> run-time
\r
1954 ( do dx dd --- ) indexed mode >-/
\r
1955 Compile an assembler of binary operators, with primary op-code
\r
1956 (accumulator form, any mode) ub, count of other codes (0, 1, or
\r
1957 5) b, and optional list of other codes ul. The list of other
\r
1958 op-codes must be pushed on the stack in the order S, U, Y, X,
\r
1959 and D (LD, ST, and CMP), or must be just the op-code for D (ADD
\r
1960 and SUB). Page escape codes must be included in the op-codes.
\r
1961 Run-time operands: ds is the source, do is the source
\r
1962 offset/auto mode, dx is the index mode/register, dd is the
\r
1963 destination register. Example: 12 # D CMP is cmpd #12 -800. X )
\r
1964 X LD is ldx [-800,x]
\r
1966 REG-REG ( b --- ) { b REG-REG name } input -> compile-time
\r
1967 ^a ( d1 d2 --- ) -> run-time
\r
1968 Compile an assembler of register d1 to register d2 moves.
\r
1969 Examples: D Y EXG is exg d,y
\r
1970 A CC TFR is tfr a,c
\r
1974 REG-BITS ( n --- vadr )
\r
1975 ^a 1ARRAY of register bits for push/pull extension byte. The
\r
1976 Undefined slots set all bits to stabilize PACK. Use the low
\r
1977 word of a register specifier to index the array (see the DREG
\r
1980 PACK ( n dl n --- n b )
\r
1981 ^ Pack register list dl into result byte b. Terminates when the
\r
1982 n, which is not the high word of a register specifier, is DUPed
\r
1983 and compared to HEX 5245; thus, any word or double which won't
\r
1984 be interpreted as a register specifier (see DREG) will terminate
\r
1985 the list, including the stack hole. ERRORs on attempt to push a
\r
1986 stack register on itself. May underflow the parameter
\r
1987 stack if the stack hole is corrupted with HEX 5245, of course,
\r
1988 but will not attempt to draw more than 8 doubles from the stack
\r
1989 unless REG-BITS is corrupted.
\r
1991 MOVEM ( b --- ) { b MOVEM name } input -> compile-time
\r
1992 ^a ( n dl d --- n ) -> run-time
\r
1993 Compile a push or pull instruction assembler. d is the stack
\r
1994 register to push or pull. See PACK.
\r
1995 Example: D X Y U PSH is pshu d,x,y
\r
1996 (But don't leave stray register specifiers on the stack!)
\r
2001 A Assemble a branch on condition d2 to absolute address d1.
\r
2002 Converts to PC relative, assembles a short branch if branch
\r
2003 target is close enough.
\r
2004 Example: LABEL 0 CCLR BR is bcc [LABEL]
\r
2006 DCOND ( n --- ) { n DCOND name } input -> compile-time
\r
2008 Compile a branch condition constant; high word is HEX 434F.
\r
2009 Always (AL), never (NV), and subroutine (SR) are provided as
\r
2011 Example: ' BMUL CFA 0 AL BR is bra BMUL
\r
2013 CC-IMM ( b --- ) { b CC-IMM name } -> compile-time
\r
2014 ^a ( d --- ) -> run-time
\r
2015 Compile ORCC, ANDCC, EORCC, or CWAI assemblers. The assemblers
\r
2016 will ERROR if the operand is not immediate.
\r
2017 Example: HEX EF # CWAI is cwai #$EF
\r
2019 IMPLY ( b --- ) { b IMPLY name } input >--> compile-time
\r
2020 ^a ( --- ) run-time
\r
2021 Compile assemblers of implicit operand instructions.
\r
2022 Example: NOP is nop
\r
2024 **** The next two SCREENs contain op-code assemblers. ****
\r
2025 See the compilers for run-time descriptions. The odd organization keeps
\r
2026 the trees balanced. The assemblers, or, in other words, the mnemonics,
\r
2027 are in the ASSEMBLER vocabulary.
\r
2031 BINARYs LD ST and CMP with their associated 16-bit register op-code
\r
2033 MOVEMs PUL PSH UNARYs ROR ROL IMPLYs RTS RTI
\r
2034 BINARY SBC DCOND SR (subroutine) REG-REG TFR
\r
2035 UNARY TST BINARY SUB with D
\r
2036 IMPLYs SWI2 SWI3 SWI SYNC BINARYs AND ADC
\r
2037 UNARYs ASL ASR BINARY ADD with D IMPLY ABX
\r
2038 DCOND CS UNARYs COM CLR DCOND AL (always)
\r
2039 BINARY BIT UNARY DEC IMPLY DAA
\r
2040 DCONDs HI MI EQ GE REG-REG EXG UNARY INC
\r
2041 BINARY JSR UNARY JMP BINARY EOR
\r
2042 DCONDs GT HS IMPLY NOP DCONDS LS PL
\r
2046 UNARYs LSR LSL DCONDs LT NE IMPLY MUL
\r
2047 UNARY NEG BINARY OR CC-IMM ORCC
\r
2048 DONCD NV (never) IMPLY SEX (blush) CC-IMMs ANDCC CWAI
\r
2049 DCONDs VC VS CCLR (Carry CLeaR)
\r
2051 EA-IX ( n --- vadr )
\r
2052 ^a 1ARRAY of translations from register (DREG) to LEA arguments.
\r
2054 LEA ( do dx dd --- )
\r
2055 A Assembler for LEA instructions. do is the offset/auto mode, dx
\r
2056 is the source index register, dr is the destination index
\r
2058 Example: D Y , X LEA is leax d,y
\r
2064 [CD] ( --- dcfa ) { [CD] name } input P
\r
2065 A Produce the CFA of the following definition header, for use as a
\r
2066 jump or indexing target. If compiling, causes the code address
\r
2067 to be compiled as a double literal; otherwise, pushes the cfa as
\r
2068 a double, so the assemblers can use it for addressing.
\r
2070 & ! ^ ( n1 n2 --- n3 )
\r
2071 A Aliases for AND OR and XOR for the assembler vocabulary.
\r
2074 A Assembler the NEXT instruction, jmp [,y++].
\r
2076 **** The assembler control constructs are patterned after FORTH
\r
2077 control constructs, but test the Condition Code register.
\r
2082 INVERTCC ( dcond --- ~dcond )
\r
2083 ^a Invert the assembler branch condition (double word) on top of
\r
2086 LIF ( dcond --- daddr )
\r
2087 A Mark HERE as a double with the address in the low word and HEX
\r
2088 4146 in the high word. Assemble a long branch on the inverse of
\r
2089 the condition given, and leave the mark. Temporarily set the
\r
2090 branch address to the RES-ERROR routine.
\r
2092 IF ( dcond --- daddr )
\r
2093 A Same as LIF, but assembles short branch with 0 offset.
\r
2097 FILL-IN ( dadr --- )
\r
2098 ^a Resolve offset of branch at mark to HERE, handle two, three, and
\r
2099 four byte branches.
\r
2103 ELSE ( daddr1 --- daddr2 )
\r
2104 A ERROR check the mark daddr1, mark HERE and assemble short branch
\r
2105 always, via IF, and FILL-IN the previously marked IF or LIF.
\r
2107 LELSE ( daddr1 --- daddr2 )
\r
2108 A Same as ELSE except mark and assemble long branch always via
\r
2111 ENDIF ( daddr --- )
\r
2112 A ERROR check the mark, and resolve the IF or LIF.
\r
2114 BEGIN ( --- daddr )
\r
2115 A Mark indefinite loop beginning with HERE. High word of mark is
\r
2118 UNTIL ( daddr dcond --- )
\r
2119 A ERROR if daddr is not BEGIN mark; assemble branch on inverse of
\r
2120 condition dcond to address marked in daddr.
\r
2122 WHILE ( daddr dcond --- adr daddr )
\r
2123 A ERROR if daddr is not BEGIN mark; assemble forward branch on
\r
2124 inverse of condition dcond, leave BEGIN address on stack and
\r
2125 extend mark with WHILE address and mark, HEX 4157.
\r
2127 REPEAT ( adr daddr --- )
\r
2128 A ERROR if not WHILE mark, assemble a branch to the BEGIN address
\r
2129 and FILL-IN the WHILE address.
\r
2131 LWHILE ( daddr dcond --- adr daddr )
\r
2132 A Forced long branch version of WHILE.
\r
2137 A CREATE a header and store the parameter stack pointer in CSP to
\r
2138 mark the stack for assembler control construct and other errors.
\r
2141 A ERROR check CSP and un-smudge the definion. NEXT must be
\r
2142 explicitly assembled.
\r
2145 A Shift to high-level compiling. (Assembles jmp <XCOL, changes
\r
2146 state to compiling, changes interpretation vocabulary to
\r
2147 definition vocabulary.)
\r
2150 A Shift to assembly language. (Compiles (MACHINE), changes state
\r
2151 to interpretation, sets interpretation vocabulary to assembler.)
\r
2157 B Store double d at adr.
\r
2160 B Fetch double (two words) at adr.
\r
2162 DOVER ( d1 d2 --- d1 d2 d1 )
\r
2163 B Copy the second double (bytes 4-7) on the stack to the top.
\r
2165 DSWAP ( d1 d2 --- d2 d1 )
\r
2166 B Swap the top two doubles (bytes 0-3 with bytes 4-7).
\r
2170 This is an example showing use of the dictionary to associate
\r
2171 pairs, from one of the textbooks I have. I apologize to the source for
\r
2172 not giving proper credit, but I can't find it. It is included to show
\r
2173 use of DOES> and to show how having the symbol table handy at run-time
\r
2174 can be taken advantage of. It builds pairs of objects linked to each
\r
2175 other such that typing one in results in printing the other out.
\r
2178 *******************************************************************************
\r
2179 Some Thoughts and Comments:
\r
2182 Hey, it's not a professional package, so I can put this here if I want!
\r
2184 One of the problems with BIF is the power of the 6809. It is all too
\r
2185 easy to use 6809 instructions instead of icodes. This means that the
\r
2186 6809 architecture gets woven into BIF, as mentioned at the end of the
\r
2187 discussion on the virtual machine.
\r
2189 BIF can probably be made to conform with one of the standards by moving
\r
2190 the virtual machine routines to their associated definitions (XCOLON to
\r
2191 COLON, XVAR to VARIABLE, etc.) and by making all code fields three-byte
\r
2192 jumps (JSRs). Direct threading will probably not be a problem, as long
\r
2193 as code fields are uniform in size.
\r
2195 The constant shifting between modes which I have done makes a built-in
\r
2196 debugger more complex, as well. One specific example is that using a
\r
2197 macro instead of a jump to a NEXT inner interpreter makes debugging more
\r
2198 complex. If there is an inner interpreter, and if the low level
\r
2199 routines are known to be error free, the debugger can simply be a jump
\r
2200 inserted in the NEXT routine. Use of a macro forces the debugger to be
\r
2201 sensitive to the 6809 architecture, and requires either use of the SWI
\r
2202 method (which can't be used in ROM), CPU emulation, or external
\r
2203 breakpoint/single-step hardware. The latter method is more complete,
\r
2204 but inserting a debugging routine in the inner interpreter is often all
\r
2205 that is necessary.
\r
2207 A possible inner interpreter for a direct threaded FORTH (could be
\r
2208 located in the direct page):
\r
2211 jmp ,x 3~ 14~ (w/ jmp <NEXT)
\r
2213 Or for indirect threading:
\r
2215 jmp [,x] 6~ 17~ (w/ jmp <NEXT)
\r
2220 The apparent disadvantages of the above are at least partially offset by
\r
2221 the fact that X will contain the CFA on entry to the characteristic
\r
2222 routines. In other words, X can substitute for W, and there is no need
\r
2223 to store the CFA of the executing low level routine in an external
\r
2224 register (on the stack, in the case of BIF). Showing how this affects
\r
2225 XCOL, for direct threading:
\r
2227 someDEF jmp XCOL 4~
\r
2231 jmp <next 3~ 19~, total 33~
\r
2233 For indirect threading:
\r
2235 someDEF fdb XCOL 0~
\r
2239 jmp <NEXT 3~ 15~, total 32~
\r
2242 someDEF jsr <XCOL 7~
\r
2246 tfr x,y (leay ,x) 6~ (4~)
\r
2247 jmp [,y++] 9~ 33~, total 42~
\r
2249 SURPRISED? I was. Of course, the characteristic routines must be a
\r
2250 little careful to use or save X before they clobber it, but that isn't
\r
2251 as difficult as it might seem.
\r
2253 The direct page might still be used to locate the per-USER table, or
\r
2254 might even contain it. At first glance, it would appear too expensive
\r
2255 to offset the DP register with a variable index. But compare the
\r
2256 following to the code in BIF:
\r
2259 ldb [,s++] 10~ (stored as byte offset)
\r
2260 pshu d 7~ (there's the address)
\r
2261 jmp [,y++] 9~ 32~ compared to 34~
\r
2263 If X is used for the temporary W register as in the indirect threaded
\r
2264 inner interpreter example above, we can get the following, which speaks
\r
2268 clrb 2~ (showing word offset, )
\r
2269 addd 2,x 7~ (byte would be shorter)
\r
2273 Ah, experience. What we have to go through to get it!
\r
2275 The key to FORTH and its dialects is found in ;CODE and DOES>. By
\r
2276 providing both characteristic behaviour and data allocation, FORTH words
\r
2277 (symbols/definitions) are primitive objects. A full object-oriented
\r
2278 language could be generated with FORTH, but then you would probably have
\r
2279 SMALLTALK!. A standard compiling language keeps the symbol table, its
\r
2280 data, and the code that accesses it entirely separate, and wastes a lot
\r
2281 of code space doing so. Professional FORTH systems can strip the symbol
\r
2282 table out of compiled applications, if necessary, but the symbol table
\r
2283 is available at run-time until the programmer is satisfied that his
\r
2284 program is bug-free. Moreover, the programmer has access to the same
\r
2285 library used by the language, which is usually not the case with
\r
2286 compiled languages, even with C.
\r
2288 A careful examination of the overhead in FORTH shows that it is
\r
2289 approximately the same as the overhead in a good C compiler. While it
\r
2290 would appear that constantly moving stuff on and off the stack would be
\r
2291 a hindrance to progress, a second look reveals that the accumulator
\r
2292 bottleneck requires this kind of movement. I wish I had time and
\r
2293 facilities to examine this specific question in relation to a large
\r
2296 I sometimes wonder if management paranoia (PROTECT OUR INTELLECTUAL
\r
2297 PROPERTY!) is the primary reason FORTH, LISP, and SMALLTALK have not
\r
2298 entirely supplanted the compiled languages. If so, why is management
\r
2299 willing to hide, protect, and hang on to code, but not willing to hang
\r
2300 on to the engineers in whose brains the technology really resides? Or
\r
2301 in the converse, if management can see that it is sometimes necessary to
\r
2302 let people go, why can't they see that there are some things that are
\r
2303 not worth the cost of trying to protect their tools from? And why can't
\r
2304 they see that a intellectual property stolen by copying still requires a
\r
2305 large investment in somebody's time to learn to use it? Why doesn't
\r
2306 public domain code get used? Because it costs better than an order of
\r
2307 magnitude more to learn how to use it than it does to get it.
\r
OSDN Git Service
