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 THE AUTHORS DISCLAIM ALL
\r
21 WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
\r
22 WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
\r
23 AUTHORS BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
\r
24 DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
\r
25 PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
\r
26 TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
\r
27 PERFORMANCE OF THIS SOFTWARE.
\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 at gmail dot 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 Current on-line versions of Brodie's work will need some adjustment
\r
112 to work with this dialect of Forth.
\r
114 The object contains a simple one-sector editor (for 32-column screens)
\r
115 in the EDITOR vocabulary. It does not provide search and replace, but
\r
116 it is sufficient, for the patient, to write code. My apologies for it.
\r
117 I did not have a Color Computer 3 when I wrote the original code, and
\r
118 haven't had the time to update it. Those with access to the fig-FORTH
\r
119 Installation Manual should have no problem installing the editor shown
\r
122 The assembler in the BIF screens is a full postfix assembler. The
\r
123 double integer screens show a quick example of its use. (Theoretically.)
\r
126 *******************************************************************************
\r
127 Getting BIF Running
\r
130 Before you start, remember that BIF has the same post-fix grammar as
\r
131 FORTH. Think Reverse Polish, as in HP calculators.
\r
133 Computer: Comments:
\r
136 LOADM "BIF.BIN" from whichever drive it is on, then remove all disks and
\r
137 EXEC &H1300 BIF should tell you it is running with
\r
140 At this point, see if BIF is really running by typing
\r
141 VLIST and hitting ENTER. You should see a listing of your
\r
142 main vocabulary (symbol table) which should run on for
\r
143 about 200 entries, and then the computer responds with
\r
144 OK If this doesn't happen, you have a bad object file, get
\r
145 a new copy. Otherwise, you have BIF!
\r
147 If you have my BIF screens disk, put it in drive 0.
\r
149 6 LOAD to load the utilities starting at screen 6. After the
\r
150 utilities are loaded, you can load the assembler by
\r
154 If you don't have the BIF screens disk with the error
\r
156 0 WARNING ! and BIF responds with
\r
157 OK but now tells you error numbers instead of messages.
\r
159 Okay, a few examples:
\r
163 puts the ascii character 42 (asterisk if the current BASE is DECIMAL) on
\r
168 prints the product of 5 and 6 (30, base ten) on the output device.
\r
170 DECIMAL : CHARS 32 DO I . I EMIT CR LOOP ;
\r
173 will set up a BIF "word" called CHARS, which, being invoked on the second
\r
174 line, will print the characters and hexadecimal ascii codes from SPACE
\r
175 up to, but not including, DASH.
\r
177 The BIF screens disk should always be in drive 0 if you want real error
\r
178 messages. If you want to look at the message text, the messages are at
\r
179 the front of TOOLS.G00, after the directory screen and title screen.
\r
180 Each message takes exactly 32 characters, including spaces and
\r
181 non-printing characters. Numbering starts with 0. If you have some
\r
182 other disk in drive 0 you will get funny and not exactly intelligent
\r
183 error messages. I know it's weird, but I was following the fig-FORTH
\r
184 model, which is designed for very limited memory.
\r
186 If you haven't been able to put the BIF screens disk together, you don't
\r
187 really need it to play around with BIF, but do clear the WARNING
\r
188 variable so BIF will know error messages are not available. Aside from
\r
189 the error messages in drive 0, there is nothing special about screens
\r
190 disks, except they do not have directory tracks. You should generally
\r
191 not put them in your drives when running under BASIC (DECB), OS-9 or
\r
192 some other system. By tradition, programmers use the first several
\r
193 screens as a hand-typed directory. You can format fresh BIF disks with
\r
194 either Disk Extended Color BASIC's DSKINI or OS-9's format. BIF ignores
\r
195 the directory information both systems write, so you also generally
\r
196 should not put a real DECB or OS-9 disk in while BIF is running.
\r
198 If you do format with OS-9, format single-sided (I used DECB's disk
\r
199 interface routines so BIF can't do double sided) with as many tracks as
\r
200 you want. To use the extra tracks, or a third or fourth drive, you will
\r
201 need to modify the DRIVE-OFFSET array. Pick a standard disk
\r
202 configuration and stick with it.
\r
204 An important word of warning. BIF, like FORTH, uses buffered I/O. Your
\r
205 screens are not actually saved to disk until you cause the system to
\r
206 need enough new buffers to write your editing back to the disk. To
\r
207 force the system to save the buffers, give BIF the SAVE-BUFFERS command.
\r
210 *******************************************************************************
\r
214 EDITOR gets you into the EDITOR vocabulary.
\r
215 0 QLIST lets you look at the first sector of the directory.
\r
216 4 B/SCR * QLIST lets you look at the first eight error messages.
\r
217 DECIMAL makes sure your conversion base is base ten.
\r
219 lets you edit the first sector of the pairing example.
\r
220 Use the cursor keys to move around; use the BREAK key to
\r
221 get out. If you modified something you don't want to
\r
223 EMPTY-BUFFERS and ENTER. If you want to make sure your changes are
\r
224 written to the disk, type
\r
225 SAVE-BUFFERS and ENTER.
\r
227 The QUICK editor is in the EDITOR vocabulary. It is available at boot
\r
228 up. You'll need to get into the EDITOR vocabulary, to access it. Pass
\r
229 it a sector number, not a screen number. Multiplying by B/SCR (which
\r
230 happens to be 4) will convert a screen number to a sector number. Add
\r
231 1, 2, or 3 to the base sector number of a screen to get the sector
\r
232 numbers for the second, third, and fourth sectors of that screen.
\r
234 The editor has no find/replace or block functions. Again I apologize
\r
235 for the editor, but I found it surprisingly workable. Note that the
\r
236 utility screens contain routines to move/copy sectors, so all is not
\r
237 entirely mud. One more glitch. Lower case letters will show as VDG
\r
238 codes until you run the cursor over them. What can I say?
\r
240 During editing, all arrow keys are cursor controls. Use SHIFT-LEFTARROW
\r
241 for destructive backspace, SHIFT-DOWNARROW for `[' left bracket,
\r
242 SHIFT-RIGHTARROW for `]' right bracket, SHIFT-UPARROW for `_' underscore
\r
243 (back-arrow on CoCo2). SHIFT-CLEAR escapes the UP-ARROW to provide the
\r
244 `^' caret. SHIFT-CLEAR also escapes itself to provide the backslash.
\r
246 Perhaps this is as good a place as any to mention a few points of
\r
247 terminology. A block is a sector. Sectors are numbered sequentially
\r
248 from 0. Sector numbering continues sequentially from drive n to drive
\r
249 n+1, see DRIVE-OFFSET, but also see OFFSET. A SCREEN is a kilobyte
\r
250 worth of blocks, in this case, four 256-byte sectors. SCREEN numbering
\r
251 also begins with 0. (SCREENs are called SCREENs because a SCREEN can be
\r
252 displayed on 16 lines of a 64-column CRT screen.) You will notice that
\r
253 a CoCo 2 can't properly display and edit a whole SCREEN. Finally,
\r
254 forward blocks are control constructs, not disk sectors.
\r
257 *******************************************************************************
\r
258 The BIF Virtual Machine
\r
262 UP [DP] pointer to the per-USER variable table (USER Pointer)
\r
263 IP Y pointer to the next definition (Instruction Pointer)
\r
264 RP S return/control stack pointer
\r
265 SP U parameter/data stack pointer
\r
266 W [S] pointer to executing definition's parameter field
\r
268 The BIF Virtual Machine
\r
271 { bifc_vm.c bif.m bifdp.a
\r
272 NEXT ( --- ) jmp [,y++] (macro in bif.m)
\r
273 Causes the next definition to execute.
\r
275 DOCOL ( *** IP ) jsr <XCOL (see bif.m, bifdp.a)
\r
276 Characteristic of a colon (:) definition. Begins execution of a
\r
277 high-level definition, i. e., nests the definition and begins
\r
278 processing icodes. Mechanically, it pushes the IP (Y register)
\r
279 and loads the Parameter Field Address of the definition which
\r
280 called it into the IP.
\r
282 { symbol.c bif.m bifdp.a
\r
283 DOVAR ( --- vadr ) jsr <XVAR (bif.m, bifdp.a)
\r
284 Characteristic of a VARIABLE. A VARIABLE pushes its PFA address
\r
285 on the stack. The parameter field of a VARIABLE is the actual
\r
286 allocation of the variable, so that pushing its address allows
\r
287 its contents to be @ed (fetched). Ordinary arrays and strings
\r
288 that do not subscript themselves may be allocated by defining a
\r
289 variable and immediately ALLOTting the remaining space.
\r
290 VARIABLES are global to all users, and thus should have been
\r
291 hidden in resource monitors, but aren't.
\r
293 DOCON ( --- n ) jsr <XCON (bif.m, bifdp.a)
\r
294 Characteristic of a CONSTANT. A CONSTANT simply loads its value
\r
295 from its parameter field and pushes it on the stack.
\r
297 DOUSER ( --- vadr ) jsr <XUSER (bif.m, bifdp.a)
\r
298 Characteristic of a per-USER variable. USER variables are
\r
299 similiar to VARIABLEs, but are allocated (by hand!) in the
\r
300 per-user table. A USER variable's parameter field contains its
\r
301 offset in the per-user table.
\r
303 DOVOC ( --- ) jsr <XVOC (bif.m, bifdp.a)
\r
304 Characteristic of a VOCABULARY. A VOCABULARY stores a pointer
\r
305 to itself in the current interpretation ROOT per-USER variable.
\r
306 It contains a pointer to the definition at the root of its
\r
307 symbol table tree. This allows the symbol table routines to
\r
308 treat the root as a leaf node. This is also not standard FORTH!
\r
310 ( --- PFA ) ( *** IP ) jsr <XDOES (routine in bifdp.a)
\r
311 Characteristic of a DOES> defined word. The characteristics of
\r
312 DOES> definitions are written in high-level icodes rather than
\r
313 machine level code. The first parameter word points to the
\r
314 high-level characteristic. This routine's job is to push the
\r
315 IP, load the high level characteristic pointer in IP, and leave
\r
316 the address following the characteristic pointer on the stack so
\r
317 the parameter field can be accessed.
\r
319 The following are not standard FORTH characteristics:
\r
321 DO1ARR ( index --- eadr ) jsr <X1ARR (bif.m, bifdp.a)
\r
322 Characteristic of a linear array. Linear arrays take the top
\r
323 word on the stack as an index to the array, and return the
\r
324 address of the element indexed. So this routine subtracts the
\r
325 base index of the array, limit checks the result, then
\r
326 multiplies by the size of the array elements. If the index is
\r
327 out of bounds, it returns a NULL pointer (0). At some point I
\r
328 intended to implement multi-dimensional arrays in a similar
\r
329 manner, but I haven't. It would be a quick and interesting
\r
330 project for anyone interested.
\r
332 DOUCON ( --- n ) jsr <XUCON (bif.m, bifdp.a)
\r
333 Characteristic of a USER variable treated as a CONSTANT, i. e.,
\r
334 fetches the value stored at the specified offset in the per-user
\r
337 ( --- d ) jsr <XDCON (bifdp.a)
\r
338 Characteristic of a double integer constant; the parameter field
\r
339 contains two words instead of one, both of which get pushed.
\r
342 ADDTOP (MACRO in BIF.M) is not a characteristic; is used in several
\r
343 routines to add a value to the top of stack.
\r
346 One of the primary problems with extending BIF is that calls to the
\r
347 built-in characteristics are not conform to ;CODE. Defining definitions
\r
348 which use (;CODE) to establish the characteristics of the
\r
349 sybmbols/definitions they define will hav a three-byte code field, where
\r
350 the built-in compiling definitions -- VARIABLE, (1ARRAY, etc.,)
\r
351 CONSTANT, USER, :, and VOCABULARY have two-byte code fields. One
\r
352 specific example of the difficulties this can create is that
\r
353 vocabularies with special properties built in BIF, rather than by hand,
\r
354 can't be searched by BIF's symbol table search routine, -FIND. Of
\r
355 course, XVOC could be moved to VOCABULARY, where it belongs, (and might
\r
356 also be changed to a DOES> definition, but I don't think that's
\r
357 necessary on the 6809).
\r
360 *******************************************************************************
\r
361 The BIF Symbols/Definitions/Routines
\r
364 I have added slightly to the FORTH documentation methods. I also show
\r
365 the results on the return stack and in the input buffer, where
\r
366 appropriate. The name on the left is the definition name, as it will be
\r
367 found by ' (TICK) and the outer interpreter. To the right I indicate
\r
368 precedence (P for higher Precedence than definition) and restrictions (C
\r
369 for Compile-only). Below the name, I indicate the assembler source
\r
370 label, where it is different from the name. The definitions on the
\r
371 SCREENS disk also indicate screen and sector for the source.
\r
373 The parameters attempt to be mnemonic. It will help to remember that
\r
374 there are no stack items smaller than 16 bits; character and byte
\r
375 parameters will be integers with their high-bytes ignored. Double
\r
376 integers are 32 bits. A further reminder, parameters are listed Pascal
\r
377 order, first pushed first; thus, the right-most is at the top of stack,
\r
378 or the lowest address. I specify a list of doubles pushed onto the
\r
379 stack (used in the assembler) as dl. Finally, I will try to mean 16-bit
\r
380 integer when I say word, but I may sometimes slip and mean (per FORTH
\r
381 jargon) a definition/routine.
\r
383 Flags are slightly different than fig-FORTH -- true is set as -1, sensed
\r
384 as non-zero. False is zero, of course.
\r
386 A number of routines (such as ENCLOSE) accept and return different
\r
387 parameters than specified in fig-FORTH. I assume that those for whom
\r
388 this fact may be of consequence will have copies of the standard and can
\r
389 compare at their leisure.
\r
391 The definitions are not alphabetized, nor are they listed in order of
\r
392 immediate interest, but they are organized by the source file they occur
\r
393 in. The following file descriptions are generally accurate, but some
\r
394 code is out of place.
\r
396 BIF contains most of the virtual machine.
\r
398 BIF.M contains the inner interpreter macro, some important
\r
399 symbol table offsets, and a few other general EQUates and
\r
402 BIFDP contains the rest of the virtual machine.
\r
404 BIFU contains the allocation of the per-user system variables.
\r
406 BIFST contains the boot up code and definitions.
\r
408 BIF1 contains most of the calculator-style expression evaluator.
\r
410 BIF2 is mostly constants and system variables, but contains the
\r
411 memory management primitives.
\r
413 Most of BIF3 is code which interacts with system variables, for
\r
414 example, the words which set the conversion base to sixteen,
\r
417 BIF4 contains multiplication and division, and the disk
\r
418 interface primitives.
\r
420 BIF5 is mostly output formatting.
\r
422 BIF6 is mostly input formatting and terminal interface.
\r
424 BIF7 contains most of the dictionary (interactive symbol table)
\r
427 Unless otherwise noted, all definitions are in the BIF vocabulary.
\r
429 There is much that is not sacred about FORTH and its dialects. For
\r
430 many, the attraction of FORTH is the great abandon with which one may
\r
431 play games with its inner workings. I have taken a number of liberties
\r
432 and these routines still function. If you have an idea, back your disks
\r
436 **** Definitions/Routines in BIF.ASM and BIFB.A:
\r
439 FETCH Replace address on stack with the word at the address.
\r
443 STORE Store second word on stack at address on top of stack.
\r
446 Push the following word from the instruction stream as a
\r
447 literal, or immediate value.
\r
450 Push a double integer literal (see LIT).
\r
453 { bifc_vm.c bif.asm
\r
454 EXECUTE ( adr --- ) C
\r
455 EXEC Jump to address on stack. Used by the "outer" interpreter to
\r
456 interactively invoke routines. (Not compile-only in fig.)
\r
458 0BRANCH ( f --- ) C
\r
459 ZBR BRANCH if flag is zero.
\r
461 1BRANCH ( f --- ) C
\r
462 TBR BRANCH if not zero. Not as useful as it might appear.
\r
465 Add the following word from the instruction stream to the
\r
466 instruction pointer (Y++). Causes a program branch.
\r
469 (LOOP) ( --- ) ( limit index *** limit index+1) C
\r
470 XLOOP ( limit index *** )
\r
471 Counting loop primitive. The counter and limit are the top two
\r
472 words on the return stack. If the updated index/counter does
\r
473 not exceed the limit, a branch occurs. If it does, the branch
\r
474 does not occur, and the index and limit are dropped from the
\r
477 (+LOOP) ( n --- ) ( limit index *** limit index+n ) C
\r
478 XPLOOP ( limit index *** )
\r
479 Loop with a variable increment. Terminates when the index
\r
480 crosses the boundary from one below the limit to the limit. A
\r
481 positive n will cause termination if the result index equals the
\r
482 limit. A negative n must cause the index to become less than
\r
483 the limit to cause loop termination.
\r
485 (DO) ( limit index --- ) ( *** limit index )
\r
486 XDO Move the loop parameters to the return stack. Synonym for D>R.
\r
488 I ( --- index ) ( limit index *** limit index )
\r
489 Copy the loop index from the return stack. Synonym for R.
\r
491 J ( --- index2 ) ( index2 limit1 index1 *** index2 limit1 index1 )
\r
492 Copy the outer loop index from the return stack. As with (DO)
\r
493 and I, J may be useful outside looping contexts.
\r
495 DIGIT ( c base --- ff )
\r
496 ( c base --- n tf )
\r
497 Translate C in base, yielding a translation valid flag. If the
\r
498 translation is not valid in the specified base, only the false
\r
501 (FIND) ( name vocptr --- locptr f )
\r
502 PFIND Search vocabulary for a symbol called name. Name is a pointer
\r
503 to a NUL terminated string of characters without count, vocptr
\r
504 is a pointer to a pointer to a definition (the length byte of a
\r
505 symbol table entry). Locptr is also a pointer to a pointer to a
\r
506 definition, such that, if the flag is false, a symbol with the
\r
507 name searched for may be inserted in proper order at that point.
\r
508 Vocptr and locptr may point to either the right or left entry of
\r
509 the order-parent entry in the symbol table, or to pointer to the
\r
510 root of a vocabulary. HIDDEN (smudged) definitions are
\r
511 lexically less than their name strings. Searches only the local
\r
512 vocabulary, from the order-parent node passed. Uses (REFIND).
\r
514 vocptr is a pointer to the parameter field of a vocabulary
\r
517 ENCLOSE ( buffer c --- s length )
\r
518 ENCLOS Scan buffer for a symbol delimited by c or ASCII NUL; return the
\r
519 length of the symbol scanned and the address of its first
\r
520 character. A length 0 and a pointer to a NUL means no symbol
\r
521 was scanned before NUL terminator was reached. (Buffer is the
\r
522 address of the buffer array to scan.)
\r
524 LITERAL ( n --- ) P
\r
525 LITER ( n --- n ) if interpreting.
\r
526 Compile n as a literal, if compiling.
\r
528 DLITERAL ( d --- ) P
\r
529 DLITER ( d --- d ) if interpreting.
\r
530 Compile d as a double literal, if compiling.
\r
533 Write c to the output device (screen or printer). Uses the ECB
\r
534 device number at address $6F, -2 is printer, 0 is screen.
\r
538 Wait for a key from the keyboard. If the key is BREAK, set the
\r
539 high byte (result $FF03).
\r
541 ?TERMINAL ( --- f )
\r
542 QTERM Scan keyboard, but do not wait. Return 0 if no key, BREAK
\r
543 ($ff03) if BREAK is pressed, or key currently pressed.
\r
546 EMIT a Carriage Return (ASCII CR).
\r
548 (;CODE) ( --- ) ( IP *** ) C
\r
549 XSCODE Compile the latest symbol as a reference to a ;CODE definition;
\r
550 overwrite the first three (3!) bytes of the code field of the
\r
551 symbol found by LATEST with a jump to the low-level
\r
552 characteristic code provided in the defining definition, and pop
\r
553 IP. The machine-level code which follows (;CODE) in the
\r
554 instruction stream is not executed by the defining symbol, but
\r
555 becomes the characteristic of the defined symbol. This is the
\r
556 usual way to generate the characteristics of VARIABLEs,
\r
557 CONSTANTs, etc., when FORTH compiles itself. BIF, however, was
\r
558 hand-optimized to take advantage of direct-page jumps. So its
\r
559 pre-compiled defining symbols with low-level characteristics
\r
560 look different from those compiled by BIF, having two bytes in
\r
561 their code fields instead of three.
\r
564 TOPRT Send output to printer via CoCo's ROM routines and the device
\r
565 number variable (see EMIT).
\r
568 TOVID Send output to CRT, converse of >PRT.
\r
571 LSHIFT Fast multiply by two.
\r
574 RSHIFT Fast divide by two.
\r
576 (REFIND) ( name vocptr --- name locptr f )
\r
577 PREF Search vocabulary for the first symbol called name. (Will find
\r
578 HIDDEN/SMUDGEd definitions.) Name is a pointer to a string of
\r
579 characters without count, vocptr is a pointer to a pointer to a
\r
580 definition (the length byte of a symbol table entry). Locptr is
\r
581 also a pointer to a pointer to a definition, such that, if the
\r
582 pointer at the pointer is NULL, a symbol with the name searched
\r
583 for may be inserted in proper order at that point. Vocptr and
\r
584 locptr may be either the right or left entry of the order-parent
\r
585 entry in the symbol table, or a pointer to the root of a
\r
586 vocabulary. Flag f will indicate by offset whether the child or
\r
587 empty slot is a left link (LFTOFF), right link (RTOFF), or
\r
588 vocabulary (PFAOFF).
\r
590 vocptr is a pointer to the parameter field of a vocabulary
\r
594 **** Definitions/Routines in BIF1.A and BIF1B.A:
\r
596 MOVE ( source target count --- )
\r
597 Copy/move count words from source to target. Moves ascending
\r
598 addresses, so that overlapping only works if the source is
\r
599 above the destination.
\r
601 CMOVE ( source target count --- )
\r
602 Copy/move count bytes from source to target. Moves ascending
\r
603 addresses, so that overlapping only works if the source is
\r
604 above the destination.
\r
606 U* ( u1 u2 --- ud )
\r
607 USTAR Multiplies the top two unsigned integers, yielding a double
\r
610 U/ ( ud u --- uremainder uquotient )
\r
611 USLASH Divides the top unsigned integer into the second and third words
\r
612 on the stack as a single unsigned double integer, leaving the
\r
613 remainder and quotient (quotient on top) as unsigned integers.
\r
615 The smaller the divisor, the more likely dropping the high word
\r
616 of the quotient loses significant bits.
\r
618 AND ( n1 n2 --- n )
\r
619 Bitwise and the top two integers.
\r
624 XOR ( n1 n2 --- n )
\r
625 Bitwise exclusive or.
\r
628 SPFEH Fetch the parameter stack pointer (before it is pushed).
\r
630 SP! ( whatever --- nothing )
\r
631 SPSTO Initialize the parameter stack pointer from the USER variable
\r
632 S0. Effectively clears the stack.
\r
634 RP! ( whatever *** nothing )
\r
635 RPSTO Initialize the return stack pointer from the USER variable R0.
\r
636 Effectively aborts all in process definitions, except the active
\r
637 one. An emergency measure, to be sure.
\r
640 SEMIS Pop IP from return stack (return from high-level definition).
\r
641 Can be used in a screen to force interpretion to terminate.
\r
643 LEAVE ( limit index *** index index )
\r
644 Force the terminating condition for the innermost loop by
\r
645 copying its index to its limit. Termination is postponed until
\r
646 the next LOOP or +LOOP instruction is executed. The index
\r
647 remains available for use until the LOOP or +LOOP instruction is
\r
650 >R ( n --- ) ( *** n ) C
\r
651 TOR Move top of parameter stack to top of return stack.
\r
653 R> ( --- n ) (n *** ) C
\r
654 RFROM Move top of return stack to top of parameter stack.
\r
656 R ( --- n ) ( n *** n )
\r
657 Copy the top of return stack to top of parameter stack. A
\r
660 = ( n1 n2 --- n1=n2 )
\r
661 EQ Flag true if n1 and n2 are equal, otherwise false.
\r
663 < ( n1 n2 --- n1<n2 )
\r
664 LT Flag true if n1 is less than n2, otherwise false.
\r
667 ZEQ Logically invert top of stack; or flag true if top is zero,
\r
671 ZLESS Flag true if top is negative (MSbit set), otherwise false.
\r
673 > ( n1 n2 --- n1>n2 )
\r
674 GT Flag true if n1 is greater than n2, false otherwise.
\r
677 + ( n1 n2 --- n1+n2 )
\r
678 ADD Add top two words.
\r
680 - ( n1 n2 --- n1-n2 )
\r
681 SUB Subtract top two words.
\r
684 D+ ( d1 d2 --- d1+d2 )
\r
685 DADD Add top two double integers.
\r
687 D- ( d1 d2 --- d1-d2 )
\r
688 DSUB Subtract top two double integers.
\r
691 Negate (two's complement) top of stack.
\r
693 DMINUS ( d --- -d )
\r
694 Negate (two's complement) top two words on stack as a double
\r
697 OVER ( n1 n2 --- n1 n2 n1 )
\r
698 Push a copy of the second word on stack.
\r
701 Discard the top word on stack.
\r
703 SWAP ( n1 n2 --- n2 n1 )
\r
704 Swap the top two words on stack.
\r
706 DUP ( n1 --- n1 n1 )
\r
707 Push a copy of the top word on stack.
\r
710 ADDSTO Add the second word on stack to the word at the adr on top of
\r
713 TOGGLE ( adr b --- )
\r
714 TOG Exclusive or byte at adr with low byte of top word.
\r
717 CFEH Replace address on top of stack with the byte at the address.
\r
718 High byte of result is clear.
\r
721 CSTO Store low byte of second word on stack at address on top of
\r
722 stack. High byte is ignored.
\r
724 ROT ( n1 n2 n3 --- n2 n3 n1 )
\r
725 Rotate the top three words on stack, bringing the third word to
\r
729 Calculate a back reference from HERE and compile it. The result
\r
730 compiled is adr-HERE-2, being adjusted for post-increment
\r
734 Bit (one's) complement the top of stack.
\r
736 ' ( --- ) compiling P
\r
737 TICK ( --- adr ) interpreting
\r
739 Parse a symbol name from input and search, -DFIND, the
\r
740 dictionary for it; compile the address as a literal if
\r
741 compiling, otherwise just push it. Recursively searches parent
\r
742 vocabularies, aborts if the parsed symbol name is not found.
\r
745 NEXSCR Continue interpreting source code on the next screen.
\r
747 1ARRAY ( start end size --- )
\r
748 ONEARR { 1ARRAY name } input
\r
749 Parse name and compile it as a linear array of size elements
\r
750 from start index to end index inclusive. The number of bytes in
\r
751 the array is (end-start+1)*size. The 1ARRAY characteristic is a
\r
752 direct page routine.
\r
755 UTIL The UTILITIES vocabulary.
\r
757 DP@ ( --- adr ) in UTILITIES
\r
758 DPFEH Calculate and push the address of the direct page.
\r
760 DCONSTANT ( d --- )
\r
761 DCON { DCONSTANT name } input
\r
762 Parse name and compile it as a double constant with a value of
\r
763 d. The DCONSTANT characteristic is a direct page routine.
\r
766 Swap the bytes of the top word on stack.
\r
769 Swap the nibbles of the top word on stack. The low-level code
\r
770 looks funny, but it was the fastest way I could think up.
\r
773 **** Definitions/Routines in BIF2.A and BIF2B.A:
\r
775 Increments and decrements for top of stack:
\r
776 1+ ADD1 ( n --- n+1 )
\r
777 1- SUB1 ( n --- n-1 )
\r
778 2+ ADD2 ( n --- n+2 )
\r
779 2- SUB2 ( n --- n-2 )
\r
787 BL BL ( --- SP ) ASCII SPACE character
\r
788 C/L CPERL ( --- 32 ) The number of columns per line on the
\r
789 CRT. Determines the length of error messages and the
\r
790 width and length of screen listings, among other things.
\r
791 FIRST ( --- adr ) The base of the disk buffer space.
\r
792 LIMIT ( --- adr ) The limit of the disk buffer space.
\r
793 B/BUF BPBUF ( --- 256 ) The size, in bytes, of a buffer.
\r
794 B/SCR BPSCR ( --- 4 ) The size, in buffers, of a screen.
\r
796 +ORIGIN ( n --- adr )
\r
797 PORIG Calculate the address of the (n/2)th entry in the boot-up
\r
798 parameter table. (Adds the base of the boot-up table to n.)
\r
801 TIB ( --- vadr ) Terminal Input Buffer address. Note
\r
802 that is a variable, so users may allocate their own
\r
803 buffers, but it must be @ed.
\r
804 WARNING WARN ( --- vadr ) Availability of error messages on disk.
\r
805 Contains 1 if messages available, 0 if not, -1 if a disk
\r
806 error has occurred.
\r
807 In bif-c, add 2 for internal error strings.
\r
808 FENCE ( --- vadr ) Boundary for FORGET.
\r
809 DP DPC ( --- vadr ) Dictionary pointer, fetched by HERE.
\r
810 ROOT ( --- vadr ) Current local/context interpretation
\r
811 vocabulary root. Not a fig variable.
\r
812 BLK ( --- vadr ) Block being interpreted. Zero refers to
\r
814 IN ( --- vadr ) Input buffer offset/cursor.
\r
815 OUT ( --- vadr ) Output buffer offset/cursor.
\r
816 SCR ( --- vadr ) Screen being edited. Unused in BIF.
\r
817 OFFSET ( --- vadr ) Sector offset for LOADing screens, set
\r
818 by DRIVE to make a new drive the default.
\r
819 STATE ( --- vadr ) Compiler/interpreter state.
\r
820 BASE ( --- vadr ) Numeric conversion base.
\r
821 DPL ( --- vadr ) Output decimal point locator.
\r
822 FLD ( --- vadr ) Field width for I/O formatting.
\r
823 CSP ( --- vadr ) Compiler stack mark for stack check.
\r
824 R# RNUM ( --- vadr ) Editing cursor location. Unused in BIF.
\r
825 HLD ( --- vadr ) Pointer to last HELD character in PAD.
\r
826 FOREWARD FORE ( --- vadr ) Pointer to earliest definition in active
\r
827 forward block. Not fig.
\r
828 CURRENT CURR ( --- vadr ) NFA of LATEST definition. Not fig.
\r
829 PREV ( --- vadr ) Most Recently Used buffer.
\r
830 USE ( --- vadr ) Least Recently Used buffer.
\r
831 DROOT ( --- vadr ) Current defining/compiling vocabulary
\r
835 Get contents of DP, with heap/stack overflow ERROR check. More
\r
836 than a pseudo-constant.
\r
839 Increase heap (add n to DP), ERROR check stack/heap.
\r
842 COMMA Store word n at DP++, ERROR check stack/heap.
\r
845 CCOMMA Store byte b at DP+, ERROR check stack/heap.
\r
855 QCST Push compile/interpret state bits.
\r
857 IF ( --- cdptr $4946 ) P,C
\r
858 Compile a 0BRANCH and dummy offset and push IF reference to fill
\r
859 in and IF control construct flag.
\r
861 ELSE ( cdptr1 $4946 --- cdptr2 $4946 ) P,C
\r
862 ERROR check IF flag, compile BRANCH with dummy offset, resolve
\r
863 IF reference (FILL-IN offset-2 to HERE at cdptr1), and leave
\r
864 reference to BRANCH for ELSE.
\r
867 ENDIF ( cdptr $4946 --- ) P,C
\r
868 ERROR check IF flag, resolve IF reference (FILL-IN offset-2 to
\r
869 HERE at cdptr) and pop reference/flag.
\r
872 **** Definitions/Routines in BIF3.A and BIF3B.A:
\r
874 LATEST ( --- symptr )
\r
875 Fetch CURRENT as a per-USER constant.
\r
877 Symbol table conversions:
\r
878 LFA ( n --- n+LFAOFF ) Convert NFA (not PFA) to LFA.
\r
879 --> Convert header address to LFA.
\r
880 CFA ( n --- n+CFAOFF ) Convert NFA (not PFA) to CFA.
\r
881 --> Convert header address to CFA.
\r
882 GFA ( n --- n+GFAOFF ) Convert NFA (not PFA) to CFA.
\r
883 --> Convert header address to GFA.
\r
884 PFA ( n --- n+PFAOFF ) Convert NFA to PFA.
\r
885 --> Convert header address to PFA.
\r
886 NFA ( n --- n-PFAOFF ) Convert PFA to NFA.
\r
887 --> Convert PFA to header address.
\r
888 NFA is the address of the length byte in a symbol table header.
\r
889 --> Now we use the header address instead of the NFA.
\r
890 PFA is the address at which a high-level definition's icode list
\r
891 begins, or a variable's, constant's, or vocabulary's value is
\r
893 CFA is where a definition's code begins, or where the jump to
\r
894 its characteristic is stored.
\r
895 LFA is the address of a definition's allocation link.
\r
896 GFA is the address of a definition's vocabulary link.
\r
899 STOCSP Save the parameter stack pointer in CSP for compiler checks.
\r
901 Set the conversion base:
\r
902 HEX ( --- ) Sixteen.
\r
903 DECIMAL DEC ( --- ) Ten.
\r
904 OCTAL OCT ( --- ) Eight.
\r
906 FILL ( adr n b --- )
\r
907 Fill n bytes at adr with b.
\r
909 ERASE ( adr n --- )
\r
910 Fill n bytes with 0.
\r
912 BLANKS ( adr n --- )
\r
913 Fill n bytes with ASCII SPACE.
\r
916 Format a character at the left of the HLD output buffer.
\r
919 Give the address of the output PAD buffer. Not same as fig. PAD
\r
920 points to the end of a 34 byte buffer for numeric conversion.
\r
923 STOD Sign extend n0 to a double integer.
\r
925 +- ( n0 n1>=0 --- n0 )
\r
926 CHS ( n0 n1<0 --- -n0 )
\r
927 Change sign of second iff top is negative.
\r
929 D+- ( d0 n0>=0 --- d0 )
\r
930 DCHS ( d0 n0<0 --- -d0 )
\r
931 Change sign of second and third as double iff top is negative.
\r
935 Change the top of stack to its absolute value.
\r
937 DABS ( d>=0 --- d )
\r
939 Change the top double to its absolute value.
\r
941 MIN ( n0 n1 --- min(n0,n1) )
\r
942 Leave the minimum of the top two integers.
\r
944 MAX ( n0 n1 --- max(n0,n1) )
\r
945 Leave the maximum of the top two integers.
\r
948 LBRAK Clear the compile state bits (shift to interpret).
\r
951 RBRAK Set the compile state bits (shift to compile).
\r
954 IMMED Toggle precedence bit of LATEST definition header. During
\r
955 compiling, most symbols scanned are compiled. IMMEDIATE
\r
956 definitions execute whenever the outer INTERPRETer scans them,
\r
957 but may be compiled via ' (TICK).
\r
960 Toggle HIDDEN bit of LATEST definition header, to hide it until
\r
961 defined or reveal it after definition.
\r
963 COMPILE-ONLY ( --- )
\r
964 COMPO Toggle compile only bit of LATEST definition header.
\r
966 COUNT ( strptr --- strptr+1 count )
\r
967 Convert counted string to string and count. (Fetch the byte at
\r
968 strptr, post-increment.)
\r
970 -TRAILING ( strptr count1 --- strptr count2 )
\r
971 DTRAIL Supress trailing blanks (subtract count of trailing blanks from
\r
974 (MACHINE) ( ip *** ) C
\r
975 XMACH Change from executing icodes to machine code in a definition by
\r
976 saving IP and jumping to it after popping the old IP.
\r
978 TYPE ( strptr count --- )
\r
979 EMIT count characters at strptr.
\r
981 CTS-TYPE ( adr --- ) in UTILITIES (bif-c)
\r
982 CTD_TYPE TYPE the (byte) counted string at adr.
\r
985 XDOTQ TYPE counted string out of instruction stream (updating IP).
\r
988 IDDOT Print definition's name from its NFA.
\r
990 FILL-IN ( cdptr --- ) C
\r
991 FILLIN Resolve the reference at cdptr by writing the offset from
\r
992 cdptr+2 to HERE at cdptr. Offset is adjusted for post-increment
\r
995 BEGIN ( --- cdptr $4245 ) P,C
\r
996 Push HERE for BACK reference for general (non-counting) loops,
\r
997 with BEGIN construct flag.
\r
999 AGAIN ( cdptr $4245 --- ) P,C
\r
1000 ERROR check BEGIN flag, compile BRANCH and BACK resolve it to
\r
1003 UNTIL ( cdptr $4245 --- ) P,C
\r
1004 ERROR check BEGIN flag, compile 0BRANCH and BACK resolve it to
\r
1007 WHILE ( $4245 --- $4245 cdptr $5748 ) P,C
\r
1008 ERROR check BEGIN flag, compile 0BRANCH with dummy offset, push
\r
1009 WHILE reference -- HERE -- /flag on top of BEGIN reference/flag.
\r
1011 REPEAT ( cdptr1 $4245 cdptr2 $5748 --- ) P,C
\r
1012 ERROR check WHILE and BEGIN flags, compile BRANCH and BACK fill
\r
1013 cdptr1 reference, FILL-IN 0BRANCH reference at cdptr2.
\r
1015 DO ( --- cdptr $444F ) P,C
\r
1016 Compile (DO), push HERE for BACK refenece, and push DO control
\r
1020 **** Definitions/Routines in BIF4.A and BIF4B.A:
\r
1022 M* ( n1 n2 --- d )
\r
1023 MSTAR Multiply top two words as signed integers with a signed double
\r
1026 M/ ( d n --- remainder quotient )
\r
1027 MSLASH Divide signed double dividend d (2nd & 3rd words) by signed
\r
1028 word divisor n (top) yielding signed word remainder and quotient.
\r
1029 Quotient is top, remainder takes sign of dividend.
\r
1031 Thus, dividend == quotient * divisor + remainder
\r
1032 with truncating toward zero.
\r
1033 This can overflow in quotient.
\r
1035 * ( multiplier multiplicand --- product )
\r
1036 STAR Signed word multiply.
\r
1038 /MOD ( dividend divisor --- remainder quotient )
\r
1039 SLAMOD M/ in word-only form, i. e., signed division of 2nd word by top
\r
1040 word yielding signed word quotient and remainder.
\r
1042 / ( dividend divisor --- quotient )
\r
1043 SLASH Signed word divide without remainder.
\r
1045 MOD ( dividend divisor --- remainder )
\r
1046 Remainder function, result takes sign of dividend.
\r
1048 */MOD ( multiplier multiplicand divisor --- remainder quotient )
\r
1049 SSMOD Signed precise division of product: multiply 2nd and 3rd
\r
1050 words on stack and divide the 31-bit product by the top word,
\r
1051 leaving both quotient and remainder. Remainder takes sign of
\r
1052 product. Guaranteed not to lose significant bits.
\r
1054 */ ( multiplier multiplicand divisor --- quotient )
\r
1055 STARSL */MOD without remainder.
\r
1057 M/MOD ( ud1 u1 --- u2 ud2 )
\r
1058 MSMOD U/ with an (unsigned) double quotient. Guaranteed not to lose
\r
1059 significant bits, if you are prepared to deal with them.
\r
1061 +BUF ( buffer1 --- buffer2 f )
\r
1062 ADDBUF Bump to next buffer, flag false if result is PREVious buffer,
\r
1063 otherwise flag true. Used in the LRU allocation routines.
\r
1066 Mark PREVious buffer dirty, in need of being written out.
\r
1068 EMPTY-BUFFERS ( --- )
\r
1069 EMTBUF Mark all buffers empty. Standard method of discarding changes.
\r
1071 DRIVE-OFFSET ( n --- eadr )
\r
1072 DROFFS 1ARRAY of drive offsets (see DO1ARR in the description of the
\r
1073 virtual machine). Contains the size, in sectors, of four
\r
1074 drives, plus a fifth entry to end the table if all four drives
\r
1075 are defined. To make drive 2 a 40 track SS-DD drive:
\r
1076 40 18 * 2 DRIVE-OFFSET !
\r
1077 (Formatting the extra tracks can be handled with OS-9.)
\r
1080 Add up the sector offset to sector 0 of drive n and store it in
\r
1081 OFFSET. This changes the logically lowest drive for LOADING.
\r
1083 R/W ( buffer sector f --- )
\r
1084 RW Read or Write the specified (absolute -- ignores OFFSET) sector
\r
1085 from or to the specified buffer. A zero flag specifies write,
\r
1086 non-zero specifies read. Sector is an unsigned integer, buffer
\r
1087 is the buffer's address. Uses the CoCo ROM disk routines. This
\r
1088 is where you would want to handle double-sided drives.
\r
1090 ?ERROR ( 0 n --- ) ( *** )
\r
1091 QERROR ( true n --- IN BLK ) ( anything *** nothing )
\r
1092 If flag is false, do nothing. If flag is true, issue error
\r
1093 MESSAGE and QUIT or ABORT, via ERROR. Leaves cursor position
\r
1094 (IN) and currently loading block number (BLK) on stack, for
\r
1097 ?COMP ( --- ) ( *** )
\r
1098 QCOMP ( --- IN BLK ) ( anything *** nothing )
\r
1099 ERROR if not compiling.
\r
1101 ?EXEC ( --- ) ( *** )
\r
1102 QEXEC ( --- IN BLK ) ( anything *** nothing )
\r
1103 ERROR if not executing.
\r
1105 ?PAIRS ( n1 n2 --- ) ( *** )
\r
1106 QPAIRS ( n1 n2 --- IN BLK ) ( anything *** nothing )
\r
1107 ERROR if n1 and n2 are unequal. MESSAGE says compiled
\r
1108 conditionals do not match.
\r
1110 ?CSP ( --- ) ( *** )
\r
1111 QCSP ( --- IN BLK ) ( anything *** nothing )
\r
1112 ERROR if return/control stack is not at same level as last !CSP.
\r
1113 Used to indicate that a definition has been left incomplete.
\r
1114 *** Actually, this checks the parameter stack. ***
\r
1116 ?LOADING ( --- ) ( *** )
\r
1117 QLOAD ( --- IN BLK ) ( anything *** nothing )
\r
1118 ERROR if not loading, i. e., if BLK is non-zero. [correction: if BLK _is_ zero!]
\r
1121 COMP Compile an in-line literal value from the instruction stream.
\r
1123 LOOP ( cdptr $444f --- ) P,C
\r
1124 ERROR check DO flag, compile (LOOP), fill in BACK reference.
\r
1126 +LOOP ( cdptr $444f --- ) P,C
\r
1127 PLOOP ERROR check DO flag, compile (+LOOP), fill in BACK reference.
\r
1130 Begin interpretation of screen (block) n. See also NEXSRC,
\r
1131 SEMIS, and ***NULLL****GGGGGHHHHTHNiTHNiTHNi
\r
1134 BUILDS Build a header for DOES> definitions. Actually just compiles a
\r
1135 CONSTANT zero which can be overwritten later by DOES>. Note
\r
1136 that <BUILDS is not IMMEDIATE, and therefore executes during a
\r
1137 definition's run-time, rather than its compile-time. It is not
\r
1138 intended to be used directly, but rather so that one definition
\r
1139 can build another. Also, note that nothing particularly special
\r
1140 happens in the defining definition until DOES> executes. The
\r
1141 name <BUILDS is intended to be a reminder of what is about to
\r
1144 DOES> ( --- ) ( IP *** ) C
\r
1145 DOES Define run-time behavior of definitions compiled/defined by a
\r
1146 high-level defining definition -- the FORTH equivalent of a
\r
1147 compiler-compiler. DOES> assumes that the LATEST symbol table
\r
1148 entry has at least one word of parameter field, which <BUILDS
\r
1149 provides. Note that DOES> is also not IMMEDIATE. When the
\r
1150 defining word containing DOES> executes the DOES> icode, it
\r
1151 overwrites the LATEST symbol's CFA with jsr <XDOES, overwrites
\r
1152 the first word of that symbol's parameter field with its own IP,
\r
1153 and pops the previous IP from the return stack. The icodes which
\r
1154 follow DOES> in the stream do not execute at the defining word's
\r
1155 run-time. Examining XDOES in the virtual machine shows that the
\r
1156 defined word will execute those icodes which follow DOES> at its
\r
1157 own run-time. The advantage of this kind of behaviour, which
\r
1158 you will also note in ;CODE, is that the defined word can
\r
1159 contain both operations and data to be operated on. This is how
\r
1160 FORTH data objects define their own behavior. Finally, note
\r
1161 that the effective code field for DOES> definitions is four
\r
1165 SCODE ?CSP to see if there are loose ends in the defining definition
\r
1166 before shifting to the assembler, compile (;CODE) in
\r
1167 the defining definition's instruction stream, shift to
\r
1168 interpreting, make the ASSEMBLER vocabulary current, and !CSP to
\r
1169 mark the stack in preparation for assembling low-level code.
\r
1170 Note that ;CODE, unlike DOES>, is IMMEDIATE, and compiles
\r
1171 (;CODE),which will do the actual work of changing the LATEST
\r
1172 definition's characteristic when the defining word runs.
\r
1173 Assembly is done by the interpreter, rather than the compiler.
\r
1174 I could have avoided the anomalous three-byte code fields by
\r
1175 having ;CODE compile in the direct page jumps to the actual
\r
1176 low-level characteristics in the defining definition, thus
\r
1177 allowing (;CODE) to write a two-byte direct-page jumps into the
\r
1178 code fields of defined words. But that's a lot of work!
\r
1181 **** Definitions/Routines in BIF5.A and BIF5B.A:
\r
1185 IPCOM COMPILE a literal out of the instruction stream, without
\r
1186 checking compiler state. Used by the assembler to stuff
\r
1187 op-codes into the instruction stream, since the assembler runs
\r
1188 in interpretation mode.
\r
1190 ?STACK ( --- ) ( *** )
\r
1191 QSTACK ( --- IN BLK ) ( anything *** nothing )
\r
1192 ERROR if either stack out of bounds, or on evidence of stack
\r
1193 boundary problems. There is a word below the bottom of each
\r
1194 stack, which ABORT clears before it starts interpreting. In
\r
1195 addition to checking that both stacks have not overflowed, this
\r
1196 routine checks those two words, to see if underflow has
\r
1199 BUFFER ( n --- buffer )
\r
1200 Get a free buffer, assign it to block n, return buffer address.
\r
1201 Will free a buffer by writing it, if necessary. Does not
\r
1202 actually read the block. A bug in the fig LRU algorithm, which
\r
1203 I have not fixed, gives the PREVious buffer if USE gets set to
\r
1204 PREVious (the bug is that it happens). This bug sometimes
\r
1205 causes sector moves to become sector fills.
\r
1207 BLOCK ( n --- buffer )
\r
1208 Get BUFFER containing block n, relative to OFFSET. If block n
\r
1209 is not in a buffer, bring it in. Returns buffer address.
\r
1211 (LINE) ( line screen --- buffer C/L)
\r
1212 XLINE Bring in the sector containing the specified line of the
\r
1213 specified screen. Returns the buffer address and the width of
\r
1214 the screen. Screen number is relative to OFFSET. The line
\r
1215 number may be beyond screen 4, (LINE) will get the appropriate
\r
1218 .LINE ( line screen --- )
\r
1219 DOTLIN Print the line of the screen as found by (LINE), suppress
\r
1222 SPACES ( count --- )
\r
1223 EMIT count spaces, for non-zero, non-negative counts.
\r
1226 BEGHSH Initialize HLD for converting a double integer. Stores the PAD
\r
1229 #> ( d --- string length )
\r
1230 ENDHSH Terminate numeric conversion, drop the number being converted,
\r
1231 leave the address of the conversion string and the length, ready
\r
1234 SIGN ( n d --- d )
\r
1235 Put sign of n (as a flag) in front of the conversion string.
\r
1236 Drop the sign flag.
\r
1238 # ( d --- d/base )
\r
1239 HASH Generate next most significant digit in the conversion BASE,
\r
1240 putting the digit in front of the conversion string.
\r
1242 #S ( d --- dzero )
\r
1243 HASHS Convert d to a numeric string using # until the result is zero.
\r
1244 Leave the double result on the stack for #> to drop.
\r
1246 D.R ( d width --- )
\r
1247 DDOTR Print d on the output device in the current conversion base,
\r
1248 with sign, right aligned in a field at least width wide.
\r
1251 DDOT Print d on the output device in the current conversion base,
\r
1252 with sign, in free format with trailing space.
\r
1254 .R ( n width --- )
\r
1255 DOTR Print n on the output device in the current conversion base,
\r
1256 with sign, right aligned in a field at least width wide.
\r
1259 DOT Print n on the output device in the current conversion base,
\r
1260 with sign, in free format with trailing space.
\r
1263 QDOT Print signed word at adr, per DOT.
\r
1266 MESS If WARNING is 0, print "MESSAGE #n"; otherwise, print line n
\r
1267 relative to screen 4, the line number may be negative. Uses
\r
1268 .LINE, but counter-adjusts to be relative to the real drive 0.
\r
1270 In bif-c, add value of 2 for WARNING, for internal error message
\r
1273 (ABORT) ( anything --- nothing ) ( anything *** nothing )
\r
1274 IABORT An indirection for ABORT, for ERROR, which may be modified
\r
1277 ERROR ( anything line --- IN BLK ) ( anything *** nothing )
\r
1278 ( anything --- nothing ) ( anything *** nothing ) WARNING < 0
\r
1279 Prints out the last symbol scanned and MESSAGE number line. If
\r
1280 WARNING is less than zero, ABORTs through (ABORT), otherwise,
\r
1281 clears the parameter stack, pushes the INput cursor and
\r
1282 interpretaion BLK, and QUITs.
\r
1284 EDITOR ( --- ) in EDITOR P
\r
1285 Set the current interpretation vocabulary to EDITOR.
\r
1287 QSYNC ( --- ) in EDITOR
\r
1288 Synchronize the ECB cursor with R#.
\r
1290 EBLK ( --- vadr ) in EDITOR
\r
1291 USER variable containing the current editing block.
\r
1293 CURSOR ( --- adr ) in EDITOR
\r
1294 Calculates the address of the edit cursor, R#, within the
\r
1295 current editing block, bringing that block in if necessary.
\r
1297 QDUMP ( adr --- ) in EDITOR
\r
1298 Dump the 256 bytes at adr to the screen memory, at the top half
\r
1299 of the screen (bottom half of screen memory).
\r
1301 QARROW ( c --- c )
\r
1303 Adjust the cursor according to the key passed. If the key is a
\r
1304 cursor control key, return 0; otherwise, leave the key
\r
1305 unchanged. The regular back-arrow is used for cursor movement,
\r
1306 so the shifted back-arrow is used for destructive backspace.
\r
1307 Also, the up arrow is used for cursor movement, so caret is not
\r
1308 available without escaping. See QUICK.
\r
1311 **** Definitions/Routines in BIF6.A and BIF6B.A:
\r
1314 (NUMBER) ( d1 string --- d2 adr )
\r
1315 INUMB Convert the text at string into a number, accumulating the
\r
1316 result into d1, leaving adr pointing to the first character not
\r
1317 converted. If DPL is non-negative at entry, accumulates the
\r
1318 number of characters converted into DPL.
\r
1320 NUMBER ( ctstr --- d )
\r
1321 Convert text at ctstr to a double integer, taking the 0 ERROR if
\r
1322 the conversion is not valid. If a decimal point is present,
\r
1323 accumulate the count of digits to the decimal point's right into
\r
1324 DPL (negative DPL at exit indicates single precision). ctstr is
\r
1325 a counted string -- the first byte at ctstr is the length of the
\r
1326 string, but NUMBER ignores the count and expects a NUL
\r
1327 terminator instead.
\r
1329 WORDPAD ( --- vadr )
\r
1330 WORDPD The per-USER constant pointing to an intermediate
\r
1331 buffer for text scanning.
\r
1334 Scan a string terminated by the character c or ASCII NUL out of
\r
1335 input; store symbol at WORDPAD with leading count byte and
\r
1336 trailing ASCII NUL. Leading c are passed over, per ENCLOSE.
\r
1337 Scans from BLK, or from TIB if BLK is zero. May overwrite the
\r
1338 numeric conversion pad, if really long (length > 31) symbols are
\r
1342 The per-USER backspace constant.
\r
1344 EXPECT ( buffer n --- )
\r
1345 Get up to n-1 characters from the keyboard, storing at buffer
\r
1346 and echoing, with backspace editing, quitting when a CR is read.
\r
1347 Terminate it with a NUL.
\r
1350 EXPECT 128 (TWID) characters to TIB.
\r
1353 NUBLK End interpretation of a line or screen, and/or prepare for a new
\r
1354 block. Note that the name of this definition is an empty
\r
1355 string, so it matches on the terminating NUL in the terminal or
\r
1358 FIND ( namstr vocptr1 --- nfa vocptr2 )
\r
1359 Search a vocabulary, and its parents, if necessary, for a
\r
1360 definition called namstr. namstr is a counted (leading count
\r
1361 byte is ignored) string, vocptr1 is a pointer to a pointer to
\r
1362 a vocabulary tree or subtree. It will usually be the address of
\r
1363 the per-USER variable ROOT or DROOT, but may be a pointer to a
\r
1364 left or right link of an entry in the symbol tree. nfa will be
\r
1365 the name field address of the definition found, or a NULL.
\r
1366 vocptr2 will be the pointer-pointer to the last vocabulary
\r
1367 searched. vocptr2 will be the last vocabulary searche. See
\r
1370 -DFIND ( --- nfa vocptr ) { -DFIND name } typical input
\r
1371 DDFIND Parse a word, then FIND, first in the definition vocabulary,
\r
1372 then in the CONTEXT (interpretation) vocabulary, if necessary.
\r
1373 Returns the address of the symbol table entry or a NULL, and the
\r
1374 last vocabulary searched, per FIND.
\r
1376 -IFIND ( --- nfa vocptr ) { -DFIND name } typical input
\r
1377 DIFIND Same as -DFIND, except search the CONTEXT vocabulary first.
\r
1379 NAME, ( --- ctStrPtr length )
\r
1380 NCOMMA Store counted string at WORDPAD into dictionary, return HERE
\r
1381 pointer and length of string. Note that the count is not stored
\r
1382 in the dictionary, but that the address returned will be the
\r
1383 address to store the count at. (The length of the names of
\r
1384 definitions are stored after the actual names in the dictionary!)
\r
1386 But in BIF-C, the lengths are stored with the strings, and the
\r
1387 address returned points to where the counted string was stored.
\r
1390 FOREMK Set forward reference bit in LATEST definition, if FOREWARD is
\r
1393 (INSTALL) ( nfa vocptr --- ) P
\r
1394 PINSTA Install the header at nfa into the specified vocabulary, hiding
\r
1395 (SMUDGEing) any existing definitions of the same name in that
\r
1396 vocabulary. In BIF-6809, vocptr was a pointer to the parameter
\r
1397 field of the vocabulary, and we follow that in BIF-C v. 0.
\r
1400 INULL Store 0 word at NULL pointer (address 0).
\r
1403 TNULL Set warning to -1 and jmp to ERROR if the word at address 0
\r
1404 (NULL pointer) is not 0.
\r
1406 QUICK ( n --- ) in EDITOR
\r
1407 Quick and dirty editor; edits sectors, not screens. See above
\r
1410 NODE. ( nfa --- flag )
\r
1411 NDOT ID. with some formatting, extra information useful for
\r
1412 debugging, and a keyboard pause/abort test. Returns flag less
\r
1413 than 0 if BREAK key was pressed.
\r
1415 VISIT ( defptr vocptr --- )
\r
1416 Scan vocabulary at vocptr in ascending order, performing
\r
1417 definition at defptr at every node. defptr is an nfa, vocptr is
\r
1418 the pfa of a vocabulary, per FIND and ROOT/DROOT. The
\r
1419 definition to be executed will have parameters of the same form
\r
1420 as NDOT, doing something at a symbol tree node and leaving a
\r
1421 termination flag. VISIT checks for stack overflow and watches
\r
1422 the termination flag between executions. The VISITing
\r
1423 definition may have other parameters, but if it changes the
\r
1424 stack pointer from execution to execution VISIT will complain.
\r
1427 Alphabetically list the definitions in the current vocabulary.
\r
1430 **** Definitions/Routines in BIF7.A and BIF7B.A:
\r
1433 CREATE ( --- ) { CREATE name } input
\r
1434 Parse a name (length < 32 characters) and create a header,
\r
1435 reporting first duplicate found in either the defining
\r
1436 vocabulary or the context (interpreting) vocabulary. (INSTALL)
\r
1437 the header in the local vocabulary.
\r
1439 CONSTANT ( n --- )
\r
1440 CONST { value CONSTANT name } typical input
\r
1441 CREATE a header, compile a call to XCON, compile the constant
\r
1444 VARIABLE ( init --- )
\r
1445 VAR { init VARIABLE name } typical input
\r
1446 CREATE a header, compile a call to XVAR, compile the initial
\r
1450 USER { uboffset USER name } typical input
\r
1451 CREATE a header, compile a call to XUSER, compile the unsigned
\r
1452 byte offset in the per-USER table. The USER is entirely
\r
1453 responsible for maintaining allocation!
\r
1456 COLON { : name sundry-activities ; } typical input
\r
1457 If executing, record the data stack mark in CSP, CREATE a
\r
1458 header, compile a call to XCOL, and set state to compile. (SCOMP
\r
1459 is defined in this file.) CONTEXT (interpretation) vocabulary
\r
1463 SEMI { : name sundry-activities ; } typical input
\r
1464 ERROR check data stack against mark in CSP, compile ;S, unSMUDGE
\r
1465 LATEST definition, and set state to interpretation.
\r
1468 DOTQ { ." something-to-be-printed " } typical input
\r
1469 Use WORD to parse to trailing quote, if compiling, compile XDOTQ
\r
1470 and string parsed, otherwise, TYPE string.
\r
1472 [COMPILE] ( --- ) P
\r
1473 BCOMP { [COMPILE] name } typical use
\r
1474 -DFIND next WORD and COMPILE it, literally; used to compile
\r
1475 immediate definitions.
\r
1478 INTERP Interpret or compile, according to STATE. Searches words parsed
\r
1479 in dictionary first, via -IFIND, then checks for valid NUMBER.
\r
1480 Pushes or COMPILEs double literal if NUMBER leaves DPL
\r
1481 non-negative. ERROR checks the stack via ?STACK before
\r
1482 returning to its caller. Sensitive to COMPILE-ONLY bit in
\r
1485 QUIT ( anything *** nothing )
\r
1486 Clear return stack. Then INTERPRET and, if not compiling,
\r
1487 prompt with OK, in infinite loop.
\r
1490 Makes BIF the current interpretation vocabulary.
\r
1492 ASSEMBLER ( --- ) P
\r
1493 ASMBLR Makes ASSEMBLER the current interpretation vocabulary. Might
\r
1494 ought not to be IMMEDIATE.
\r
1496 DEFINITIONS ( --- )
\r
1497 DEFS Makes the current interpretation vocabulary also the current
\r
1498 defining vocabulary.
\r
1500 ABORT ( anything --- nothing ) ( anything *** nothing )
\r
1501 Clear parameter stack, intialize the NULL vector, set STATE to
\r
1502 interpret and BASE to DECIMAL, return to input from terminal,
\r
1503 restore DRIVE OFFSET to 0, set interpret and define vocabularies
\r
1504 to BIF, print out "6809 BIF Vx.x", and finally, QUIT. Used to
\r
1505 force the system to a known state and return control to the
\r
1506 standard INTERPRETer.
\r
1508 VOCABULARY ( --- ) { VOCABULARY name } input
\r
1509 VOCAB Create a vocabulary entry with a NULL local pointer, linked by
\r
1510 the parent pointer to the current defining vocabulary. The
\r
1511 vocabulary parameter passed to the various searching routines is
\r
1512 usually a pointer to the parameter field of a vocabulary. That
\r
1513 way, the root is functionally identically to a left or right
\r
1514 link in a node or leaf, particularly for insertion.
\r
1517 PAREN Parse out a comment and toss it away. This is probably not
\r
1518 useful, but it leaves the first 32 characters in WORDPAD.
\r
1520 DAD ( nfa --- name linkadr flag )
\r
1521 Search the parent vocabulary of the definition at nfa for nfa,
\r
1522 returning the address of the first character of the definition's
\r
1523 name, a pointer to the left or right link which links the
\r
1524 definition in, and a flag indicating whether the definition is
\r
1525 linked left or right. ERROR if the definition can't be found.
\r
1526 The return parameters are appropriate for REPEALing the
\r
1530 Remove the CURRENT/LATEST definition from the dictionary, from
\r
1531 the vocabulary in which it is defined. Updates CURRENT, alsoe
\r
1532 updates DROOT or ROOT and clears FOREWARD, if appropriate. If
\r
1533 the CURRENT definition is in a closed forward block, repeals the
\r
1534 entire block, so that forward references aren't pointing to
\r
1537 Except that I never got that last part written and working. So
\r
1538 you have to do that by hand. It does clear FOREWARD if FOREWARD
\r
1539 is pointing to the REPEALed definition.
\r
1541 FORGET ( --- ) { FORGET name } input
\r
1542 Parse out name of definition to FORGET to, -DFIND it, then
\r
1543 REPEAL until it is removed from the dictionary. Will not FORGET
\r
1544 if definition is not found, if it is in a recursive block, or if
\r
1545 it is below FENCE; the ERROR message will include the offending
\r
1551 **** Definitions/Routines in BIFST.A
\r
1554 COLD COLD boot. Initializes the system variables, prunes the
\r
1555 dictionary of everything beyond the initial FENCE, then WARM
\r
1558 WARM Resets stack areas and per-USER variables, clears the buffers,
\r
1559 then yields control to BIF via ABORT.
\r
1563 Definitions on the SCREENs disk follow. The vocabulary names are
\r
1564 abbreviated here under the definition names, A for ASSEMBLER, B for BIF,
\r
1565 U for UTILITIES, ^a for ^asm-util.
\r
1568 Index to the screens disk.
\r
1571 Title page and copyright notice.
\r
1575 - Call the debugging monitor: SWI followed by a jmp [,y++], so
\r
1576 that BIF can be continued.
\r
1578 After screen 2 creates MON, it updates FENCE to protect MON from WARM
\r
1579 boots. Will load in the active vocabulary.
\r
1581 **** SCREENs 4 & 5
\r
1582 Error and other Messages:
\r
1583 0: number conversion/unknown definition, no message text.
\r
1584 1: DATA STACK UNDERFLOW
\r
1585 2: DICTIONARY FULL
\r
1586 3: ADDRESS RESOLUTION ERROR for control structures
\r
1587 4: HIDES DEFINITION IN some vocabulary
\r
1588 5: NULL VECTOR WRITTEN
\r
1589 6: DISC RANGE? disk sector number out of range
\r
1590 7: DATA STACK OVERFLOW
\r
1591 8: DISC ERROR! of some sort -- is your drive door closed?
\r
1592 9: CAN'T EXECUTE A NULL!
\r
1593 10: CONTROL STACK UNDERFLOW
\r
1594 11: CONTROL STACK OVERFLOW
\r
1595 12: ARRAY REFERENCE OUT OF BOUNDS
\r
1596 13: ARRAY DIMENSION NOT VALID
\r
1597 14: NO PROCEDURE TO ENTER
\r
1598 15: ( was register error message for assembler )
\r
1600 17: COMPILATION ONLY, USE IN DEFinition
\r
1601 18: EXECUTION ONLY do not use while compiling
\r
1602 19: CONDITIONALS NOT PAIRED where's your if/loop end statement?
\r
1603 20: DEFINITION INCOMPLETE often same as 18, but hit ;
\r
1604 21: IN PROTECTED DICTIONARY don't try to forget below FENCE.
\r
1605 22: USE ONLY WHEN LOADING
\r
1606 23: OFF CURRENT EDITING SCREEN an editor cursor problem
\r
1607 24: DECLARE VOCABULARY
\r
1608 25: DEFINITION NOT IN VOCABULARY
\r
1609 26: IN FORWARD BLOCK
\r
1610 27: ALLOCATION LIST CORRUPTED: LOST
\r
1611 28: CAN'T REDEFINE nul! You tried to CREATE something without a name.
\r
1612 29: NOT FORWARD REFERENCE
\r
1613 30: ( was message about IMMEDIATE )
\r
1616 33: HAS INCORRECT ADDRESS MODE for 6809
\r
1617 34: HAS INCORRECT INDEX MODE for 6809
\r
1618 35: OPERAND NOT REGISTER in 6809
\r
1619 36: HAS ILLEGAL IMMEDIATE for 6809
\r
1620 37: PC OFFSET MUST BE ABSOLUTE pc-relative addressing error
\r
1621 38: ACCUMULATOR OFFSET REQUIRED for indexing mode
\r
1622 39: ILLEGAL MEMORY INDIRECTION for 6809
\r
1623 40: ILLEGAL INDEX BASE for 6809
\r
1624 41: ILLEGAL TARGET SPECIFIED for 6809 addressing mode or register
\r
1625 42: CAN'T STACK ON SELF for push/pull, try other stack pointer
\r
1626 43: DUPLICATE IN LIST of operands
\r
1627 44: REGISTER NOT STACK trying to push on a non-stack register?
\r
1628 45: EMPTY REGISTER LIST best supply some registers
\r
1629 46: IMMEDIATE OPERAND REQUIRED for 6809
\r
1630 47: REQUIRES CONDITION for control operator
\r
1632 49: COMPILE-TIME STACK UNDERFLOW
\r
1633 50: COMPILE-TIME STACK OVERFLOW
\r
1637 BYTE-DUMP ( adr n --- )
\r
1638 U Dump n bytes to output device, right adjusted in 4 character
\r
1639 columns. Field width is not big enough if BASE is six or less.
\r
1641 DUMP ( adr n --- )
\r
1642 B Formatted dump to output device, with ASCII interpretation.
\r
1643 Hard coded to 4 bytes per line.
\r
1646 B QDUMP a block/sector and set the cursor to the middle of the
\r
1647 screen so the dump remains visible.
\r
1649 QINDEX ( start end --- )
\r
1650 B QLIST block/sectors from number start to end, inclusive.
\r
1653 U Calculate the number of terminal lines per disc screen at
\r
1654 run-time. Sixteen, at present.
\r
1656 ULIST ( n --- flag )
\r
1657 U List screen n, with line numbers in the current base, leave
\r
1658 BREAK key flag. Uses C/L, to automatically adjust for screen
\r
1659 width (if C/L is set), but you may not want to use this
\r
1660 definition if you set C/L to something besides 32 or 64.
\r
1665 B ULIST screen n, line numbers in decimal.
\r
1667 INDEX ( start end --- )
\r
1668 B Print comment lines (line 0, and line 1 if C/L < 41) of screens
\r
1669 from start to end.
\r
1672 B List a printer page full of screens to the printer, formatted by
\r
1673 C/L. Line and screen number are in current base. Lists the
\r
1674 group containing screen n, will print 2 screens if C/L is 32,
\r
1675 three if C/L is 64. (Two may not fit well.)
\r
1680 U Put the cursor at the (CoCo 2) CRT screen HOME position.
\r
1683 U Put the cursor 8 lines down the (CoCo 2) CRT screen.
\r
1686 B Clear the (CoCo 2) CRT screen.
\r
1688 CAN-UP ( adr -- adr )
\r
1689 U Clear the UPDATE bit (MSB) for the buffer whose block word is at
\r
1690 adr. The characters in the buffer should be stored at adr+2.
\r
1692 W-BUF ( adr --- adr )
\r
1693 U Write the characters at adr+2 to the sector specified at adr,
\r
1694 clear the UPDATE flag.
\r
1696 SAVE-BUF ( adr --- adr )
\r
1697 U W-BUF, if UPDATEd.
\r
1700 B Save the PREViously edited buffer, if it was UPDATEd.
\r
1702 SAVE-BUFFERS ( --- )
\r
1703 B Write all buffers flagged for UPDATE, clear UPDATE bits.
\r
1706 B Cancel UPDATE of PREViously edited buffer.
\r
1710 CANCEL-UPDATES ( --- )
\r
1711 B Cancel UPDATEs of all buffers.
\r
1714 B Re-edit PREVious buffer.
\r
1716 .BUF ( adr --- adr )
\r
1717 U Dump buffer characters at adr+2, showing the sector number
\r
1721 B Dump all buffers, with block number, per .BUF.
\r
1724 B Dump contents and block number of PREVious buffer, per .BUF.
\r
1727 B QUICK edit block n, showing the block number.
\r
1730 B QUICK edit the PREVious block.
\r
1734 QOPY ( src dest --- )
\r
1735 B Move content of block/sector src to block dest. BUG: Doesn't
\r
1736 copy if src is already in a buffer (problem with LRU).
\r
1738 COPY ( src dest --- )
\r
1739 B Copy SCREEN src to SCREEN dest. Uses QOPY, so you should
\r
1740 EMPTY-BUFFERS before using COPY.
\r
1742 QBACK ( start end --- )
\r
1743 B Copy blocks from start to end to the next higher disc, at the
\r
1744 same sector offset.
\r
1747 B Erase and then EDIT block n.
\r
1754 FORWARD ( --- ) { FORWARD name } input
\r
1755 B Compile a forward reference header: CREATE, set FOREWARD if not
\r
1756 already set, compile jmp to RES-ERROR, unSMUDGE header.
\r
1758 :RESOLVE ( --- ) { :RESOLVE name } input P
\r
1759 A If the characteristic of name is a jmp to RES-ERROR, make it
\r
1760 LATEST, re-SMUDGE it, change jmp address to HERE; if the header
\r
1761 of name is the base of the forward block, clear FOREWARD.
\r
1762 Forward blocks should end with the definition of the first
\r
1763 forward reference in the block, to maintain the block's
\r
1764 integrity. (However, the FOREWARD USER variable can be modified
\r
1765 by hand, if necessary.)
\r
1767 :RES ( --- ) { :RES name } input
\r
1768 B Do ASSEMBLER's resolve, then compile jmp <XCOL and switch state
\r
1772 B ; but SMUDGE LATEST one more time.
\r
1774 **** SCREEN 11 does not continue LOADing! ****
\r
1779 B Print 80 ASCII characters starting with '!'.
\r
1782 B PL until any key is hit.
\r
1785 B PT, but send the output to the printer.
\r
1789 SLIST ( start end --- )
\r
1790 - ULIST SCREENs to printer from start to end inclusive.
\r
1793 This contains some experimental stuff that I was using to test my a
\r
1794 Sardis Technologies disk controller.
\r
1799 B Convert the CFA on the stack to an nfa and ID. it.
\r
1801 NAMES ( adr n --- )
\r
1802 B NAME n icodes at adr. Naively interprets anything as an icode.
\r
1805 **** The assembler starts here! ****
\r
1808 A Vocabulary for assembler support stuff. (Note that the name is
\r
1809 in lower case and looks funny when editing until the cursor
\r
1812 DREG ( n --- ) { n DREG name } input -> compile-time
\r
1813 ^a ( --- d ) -> run-time
\r
1814 Define register double constants. Most significant word is
\r
1815 `RE', the index and operand encodings are masked into the least
\r
1818 xx ( --- d ) high word is HEX 5245
\r
1819 A The register double constants in hex:
\r
1820 D 52458B00 A 52458608 B 52458509 PC 52458C05
\r
1821 U 52454003 S 52456004 Y 52452002 X 52450001
\r
1822 CC 5245EF0A DP 5245EF0B
\r
1823 Example: DP A EXG is exg dp,a
\r
1826 A Suffix constant for immediate values. Becomes the high byte:
\r
1827 4 # A LD is lda #4
\r
1830 ^a DP register emulator for the assembler. A per-USER variable at
\r
1831 offset HEX 42, initialized to whatever the load-time DP is.
\r
1834 A Push the current DPREG value, as a constant. To use as an
\r
1835 absolute address, push a 0 or -1 after.
\r
1836 Example: DPR 7 + 0 JMP is jmp <7
\r
1839 A Set the DPREG value, masks the low byte of adr out.
\r
1844 ^a Compile an index byte b with signed, constant, byte or word
\r
1845 offset, n. Sets bit 0 in the index byte if it compiles a word
\r
1849 ^a Compile opcode u. Compiles 16 bits if high byte of u is
\r
1852 ABS, ( adr u1 u2 --- )
\r
1853 ^a Compile an absolute address mode (direct page or extended)
\r
1854 op-code u1, oring u2 into u1 before compiling if the address is
\r
1855 not in the direct page.
\r
1857 PCOFF ( adr n1 --- n2 flag )
\r
1858 ^a Generate a pc-relative offset n2 from adr, adjusted by n1 bytes
\r
1859 of op-code/index. Flags true if offset fit in a byte, false if
\r
1860 it required 16 bits.
\r
1862 ?ABS ( d --- adr flag )
\r
1863 ^a Convert high word of d to flag showing true if high word was 0
\r
1864 or -1, false otherwise. A 0 or -1 high word indicates an
\r
1865 absolute address as an operand.
\r
1866 Example: HEX .FF20 B OR is orb $FF20
\r
1869 ^a ERROR if d is not absolute mode operand. Calculate offset and
\r
1870 compile index byte b and offset.
\r
1874 Auto-indexing address mode double constants, in ASSEMBLER vocabulary:
\r
1875 -) ( --- 4155.0082 ) ,-r
\r
1876 )++ ( --- 4155.0081 ) ,r++
\r
1877 )+ ( --- 4155.0080 ) ,r+
\r
1878 --) ( --- 4155.0083 ) ,--r
\r
1879 Example: )++ X , D ST is std ,x++
\r
1881 MASK, ( b1 b2 --- )
\r
1882 ^a Compile the bit-or of the top two words's low bytes.
\r
1885 ^a Convert a register offset specified by u to its extension byte
\r
1886 representation, mask in the index register and indirection
\r
1887 specifier b, and compile the resulting index byte.
\r
1889 IXOFF, ( n b --- )
\r
1890 ^a Generate the appropriate index extension byte for the constant
\r
1891 offset n and indirection level specified, mask in the index
\r
1892 register and indirection specifier b, and compile both the
\r
1893 extension byte and the offset. Handles zero and 5-bit offsets.
\r
1896 ^a Compile a (completely specified) extended-indirect extension
\r
1897 byte b and the absolute address d.
\r
1902 ^a Compile an index mode address operand. n contains the index
\r
1903 register and indirection level encoding, d contains the offset
\r
1904 or auto-mode specification. Zero offset must be explicit. Does
\r
1905 not block out unsupported [,r+] and [,-r] modes.
\r
1908 A Convert indexable register d1 to index mode specifier d2.
\r
1909 Examples: 0. X , B OR is orb ,x
\r
1910 A X , JMP is jmp a,x
\r
1911 TABLE 0 PC , X LEA is leax table,pcr
\r
1914 A Convert indexable register, absolute address, or index operand
\r
1915 d1 to memory indirect operand. Note that this will NOT
\r
1916 interfere with comments.
\r
1917 Examples: TABLE 6 + 0 PC ) JMP is jmp [6,pcr]
\r
1918 )++ S ) JSR is jsr ,s++
\r
1922 ACCM ( n1 n2 n3 --- n4 )
\r
1923 ^a Convert op-code n1, register n2, and mask bits n3 to accumulator
\r
1924 encoded op-code n4. Used for encoding ACCM destination
\r
1927 UNARY ( u --- ) >--> compile-time
\r
1928 ^a { u UNARY name } input >-/
\r
1929 ( do dx --- ) indexed modes >-\
\r
1930 ( d --- ) non-indexed modes >--> run-time
\r
1931 Unary op-code compiler -- compiles an assembler of unary
\r
1932 op-codes with op-code (u) and name. Run-time parameters: d is
\r
1933 the destination register or address, dx is the index
\r
1934 mode/register, do is the offset/auto mode.
\r
1935 Examples: A NEG is nega
\r
1936 7. U , ROR is ror 7,u
\r
1938 REG ( d adr --- d u sz ) -- JSR
\r
1939 ^a ( d adr --- u sz )
\r
1940 Encode binary destination register d into op-code from table at
\r
1941 adr. Table format is primary (byte), highest (byte), secondary
\r
1942 (word) secondary (word) .... Leave op-code u and size sz (-1 is
\r
1943 word, 0 is byte) of register encoded. Helps to reduce the
\r
1944 complexity of the binary operators op-code map, see BINARY
\r
1945 concerning constructing the tables.
\r
1950 ^a Compile an immediate op-code u with immediate operand n of size
\r
1951 byte, if sz == 0, or word, ERROR if op-code is ST or JSR.
\r
1953 BINARY ( ul b ub --- ) >--> compile-time
\r
1954 ^a { ul b ub BINARY name } input >-/
\r
1955 ( ds --- ) JSR >-\
\r
1956 ( ds dd --- ) non-indexed mode >--> run-time
\r
1957 ( do dx dd --- ) indexed mode >-/
\r
1958 Compile an assembler of binary operators, with primary op-code
\r
1959 (accumulator form, any mode) ub, count of other codes (0, 1, or
\r
1960 5) b, and optional list of other codes ul. The list of other
\r
1961 op-codes must be pushed on the stack in the order S, U, Y, X,
\r
1962 and D (LD, ST, and CMP), or must be just the op-code for D (ADD
\r
1963 and SUB). Page escape codes must be included in the op-codes.
\r
1964 Run-time operands: ds is the source, do is the source
\r
1965 offset/auto mode, dx is the index mode/register, dd is the
\r
1966 destination register. Example: 12 # D CMP is cmpd #12 -800. X )
\r
1967 X LD is ldx [-800,x]
\r
1969 REG-REG ( b --- ) { b REG-REG name } input -> compile-time
\r
1970 ^a ( d1 d2 --- ) -> run-time
\r
1971 Compile an assembler of register d1 to register d2 moves.
\r
1972 Examples: D Y EXG is exg d,y
\r
1973 A CC TFR is tfr a,c
\r
1977 REG-BITS ( n --- vadr )
\r
1978 ^a 1ARRAY of register bits for push/pull extension byte. The
\r
1979 Undefined slots set all bits to stabilize PACK. Use the low
\r
1980 word of a register specifier to index the array (see the DREG
\r
1983 PACK ( n dl n --- n b )
\r
1984 ^ Pack register list dl into result byte b. Terminates when the
\r
1985 n, which is not the high word of a register specifier, is DUPed
\r
1986 and compared to HEX 5245; thus, any word or double which won't
\r
1987 be interpreted as a register specifier (see DREG) will terminate
\r
1988 the list, including the stack hole. ERRORs on attempt to push a
\r
1989 stack register on itself. May underflow the parameter
\r
1990 stack if the stack hole is corrupted with HEX 5245, of course,
\r
1991 but will not attempt to draw more than 8 doubles from the stack
\r
1992 unless REG-BITS is corrupted.
\r
1994 MOVEM ( b --- ) { b MOVEM name } input -> compile-time
\r
1995 ^a ( n dl d --- n ) -> run-time
\r
1996 Compile a push or pull instruction assembler. d is the stack
\r
1997 register to push or pull. See PACK.
\r
1998 Example: D X Y U PSH is pshu d,x,y
\r
1999 (But don't leave stray register specifiers on the stack!)
\r
2004 A Assemble a branch on condition d2 to absolute address d1.
\r
2005 Converts to PC relative, assembles a short branch if branch
\r
2006 target is close enough.
\r
2007 Example: LABEL 0 CCLR BR is bcc [LABEL]
\r
2009 DCOND ( n --- ) { n DCOND name } input -> compile-time
\r
2011 Compile a branch condition constant; high word is HEX 434F.
\r
2012 Always (AL), never (NV), and subroutine (SR) are provided as
\r
2014 Example: ' BMUL CFA 0 AL BR is bra BMUL
\r
2016 CC-IMM ( b --- ) { b CC-IMM name } -> compile-time
\r
2017 ^a ( d --- ) -> run-time
\r
2018 Compile ORCC, ANDCC, EORCC, or CWAI assemblers. The assemblers
\r
2019 will ERROR if the operand is not immediate.
\r
2020 Example: HEX EF # CWAI is cwai #$EF
\r
2022 IMPLY ( b --- ) { b IMPLY name } input >--> compile-time
\r
2023 ^a ( --- ) run-time
\r
2024 Compile assemblers of implicit operand instructions.
\r
2025 Example: NOP is nop
\r
2027 **** The next two SCREENs contain op-code assemblers. ****
\r
2028 See the compilers for run-time descriptions. The odd organization keeps
\r
2029 the trees balanced. The assemblers, or, in other words, the mnemonics,
\r
2030 are in the ASSEMBLER vocabulary.
\r
2034 BINARYs LD ST and CMP with their associated 16-bit register op-code
\r
2036 MOVEMs PUL PSH UNARYs ROR ROL IMPLYs RTS RTI
\r
2037 BINARY SBC DCOND SR (subroutine) REG-REG TFR
\r
2038 UNARY TST BINARY SUB with D
\r
2039 IMPLYs SWI2 SWI3 SWI SYNC BINARYs AND ADC
\r
2040 UNARYs ASL ASR BINARY ADD with D IMPLY ABX
\r
2041 DCOND CS UNARYs COM CLR DCOND AL (always)
\r
2042 BINARY BIT UNARY DEC IMPLY DAA
\r
2043 DCONDs HI MI EQ GE REG-REG EXG UNARY INC
\r
2044 BINARY JSR UNARY JMP BINARY EOR
\r
2045 DCONDs GT HS IMPLY NOP DCONDS LS PL
\r
2049 UNARYs LSR LSL DCONDs LT NE IMPLY MUL
\r
2050 UNARY NEG BINARY OR CC-IMM ORCC
\r
2051 DONCD NV (never) IMPLY SEX (blush) CC-IMMs ANDCC CWAI
\r
2052 DCONDs VC VS CCLR (Carry CLeaR)
\r
2054 EA-IX ( n --- vadr )
\r
2055 ^a 1ARRAY of translations from register (DREG) to LEA arguments.
\r
2057 LEA ( do dx dd --- )
\r
2058 A Assembler for LEA instructions. do is the offset/auto mode, dx
\r
2059 is the source index register, dr is the destination index
\r
2061 Example: D Y , X LEA is leax d,y
\r
2067 [CD] ( --- dcfa ) { [CD] name } input P
\r
2068 A Produce the CFA of the following definition header, for use as a
\r
2069 jump or indexing target. If compiling, causes the code address
\r
2070 to be compiled as a double literal; otherwise, pushes the cfa as
\r
2071 a double, so the assemblers can use it for addressing.
\r
2073 & ! ^ ( n1 n2 --- n3 )
\r
2074 A Aliases for AND OR and XOR for the assembler vocabulary.
\r
2077 A Assembler the NEXT instruction, jmp [,y++].
\r
2079 **** The assembler control constructs are patterned after FORTH
\r
2080 control constructs, but test the Condition Code register.
\r
2085 INVERTCC ( dcond --- ~dcond )
\r
2086 ^a Invert the assembler branch condition (double word) on top of
\r
2089 LIF ( dcond --- daddr )
\r
2090 A Mark HERE as a double with the address in the low word and HEX
\r
2091 4146 in the high word. Assemble a long branch on the inverse of
\r
2092 the condition given, and leave the mark. Temporarily set the
\r
2093 branch address to the RES-ERROR routine.
\r
2095 IF ( dcond --- daddr )
\r
2096 A Same as LIF, but assembles short branch with 0 offset.
\r
2100 FILL-IN ( dadr --- )
\r
2101 ^a Resolve offset of branch at mark to HERE, handle two, three, and
\r
2102 four byte branches.
\r
2106 ELSE ( daddr1 --- daddr2 )
\r
2107 A ERROR check the mark daddr1, mark HERE and assemble short branch
\r
2108 always, via IF, and FILL-IN the previously marked IF or LIF.
\r
2110 LELSE ( daddr1 --- daddr2 )
\r
2111 A Same as ELSE except mark and assemble long branch always via
\r
2114 ENDIF ( daddr --- )
\r
2115 A ERROR check the mark, and resolve the IF or LIF.
\r
2117 BEGIN ( --- daddr )
\r
2118 A Mark indefinite loop beginning with HERE. High word of mark is
\r
2121 UNTIL ( daddr dcond --- )
\r
2122 A ERROR if daddr is not BEGIN mark; assemble branch on inverse of
\r
2123 condition dcond to address marked in daddr.
\r
2125 WHILE ( daddr dcond --- adr daddr )
\r
2126 A ERROR if daddr is not BEGIN mark; assemble forward branch on
\r
2127 inverse of condition dcond, leave BEGIN address on stack and
\r
2128 extend mark with WHILE address and mark, HEX 4157.
\r
2130 REPEAT ( adr daddr --- )
\r
2131 A ERROR if not WHILE mark, assemble a branch to the BEGIN address
\r
2132 and FILL-IN the WHILE address.
\r
2134 LWHILE ( daddr dcond --- adr daddr )
\r
2135 A Forced long branch version of WHILE.
\r
2140 A CREATE a header and store the parameter stack pointer in CSP to
\r
2141 mark the stack for assembler control construct and other errors.
\r
2144 A ERROR check CSP and un-smudge the definion. NEXT must be
\r
2145 explicitly assembled.
\r
2148 A Shift to high-level compiling. (Assembles jmp <XCOL, changes
\r
2149 state to compiling, changes interpretation vocabulary to
\r
2150 definition vocabulary.)
\r
2153 A Shift to assembly language. (Compiles (MACHINE), changes state
\r
2154 to interpretation, sets interpretation vocabulary to assembler.)
\r
2160 B Store double d at adr.
\r
2163 B Fetch double (two words) at adr.
\r
2165 DOVER ( d1 d2 --- d1 d2 d1 )
\r
2166 B Copy the second double (bytes 4-7) on the stack to the top.
\r
2168 DSWAP ( d1 d2 --- d2 d1 )
\r
2169 B Swap the top two doubles (bytes 0-3 with bytes 4-7).
\r
2173 This is an example showing use of the dictionary to associate
\r
2174 pairs, from one of the textbooks I have. I apologize to the source for
\r
2175 not giving proper credit, but I can't find it. It is included to show
\r
2176 use of DOES> and to show how having the symbol table handy at run-time
\r
2177 can be taken advantage of. It builds pairs of objects linked to each
\r
2178 other such that typing one in results in printing the other out.
\r
2181 *******************************************************************************
\r
2182 Some Thoughts and Comments:
\r
2185 Hey, it's not a professional package, so I can put this here if I want!
\r
2187 One of the problems with BIF is the power of the 6809. It is all too
\r
2188 easy to use 6809 instructions instead of icodes. This means that the
\r
2189 6809 architecture gets woven into BIF, as mentioned at the end of the
\r
2190 discussion on the virtual machine.
\r
2192 BIF can probably be made to conform with one of the standards by moving
\r
2193 the virtual machine routines to their associated definitions (XCOLON to
\r
2194 COLON, XVAR to VARIABLE, etc.) and by making all code fields three-byte
\r
2195 jumps (JSRs). Direct threading will probably not be a problem, as long
\r
2196 as code fields are uniform in size.
\r
2198 The constant shifting between modes which I have done makes a built-in
\r
2199 debugger more complex, as well. One specific example is that using a
\r
2200 macro instead of a jump to a NEXT inner interpreter makes debugging more
\r
2201 complex. If there is an inner interpreter, and if the low level
\r
2202 routines are known to be error free, the debugger can simply be a jump
\r
2203 inserted in the NEXT routine. Use of a macro forces the debugger to be
\r
2204 sensitive to the 6809 architecture, and requires either use of the SWI
\r
2205 method (which can't be used in ROM), CPU emulation, or external
\r
2206 breakpoint/single-step hardware. The latter method is more complete,
\r
2207 but inserting a debugging routine in the inner interpreter is often all
\r
2208 that is necessary.
\r
2210 A possible inner interpreter for a direct threaded FORTH (could be
\r
2211 located in the direct page):
\r
2214 jmp ,x 3~ 14~ (w/ jmp <NEXT)
\r
2216 Or for indirect threading:
\r
2218 jmp [,x] 6~ 17~ (w/ jmp <NEXT)
\r
2223 The apparent disadvantages of the above are at least partially offset by
\r
2224 the fact that X will contain the CFA on entry to the characteristic
\r
2225 routines. In other words, X can substitute for W, and there is no need
\r
2226 to store the CFA of the executing low level routine in an external
\r
2227 register (on the stack, in the case of BIF). Showing how this affects
\r
2228 XCOL, for direct threading:
\r
2230 someDEF jmp XCOL 4~
\r
2234 jmp <next 3~ 19~, total 33~
\r
2236 For indirect threading:
\r
2238 someDEF fdb XCOL 0~
\r
2242 jmp <NEXT 3~ 15~, total 32~
\r
2245 someDEF jsr <XCOL 7~
\r
2249 tfr x,y (leay ,x) 6~ (4~)
\r
2250 jmp [,y++] 9~ 33~, total 42~
\r
2252 SURPRISED? I was. Of course, the characteristic routines must be a
\r
2253 little careful to use or save X before they clobber it, but that isn't
\r
2254 as difficult as it might seem.
\r
2256 The direct page might still be used to locate the per-USER table, or
\r
2257 might even contain it. At first glance, it would appear too expensive
\r
2258 to offset the DP register with a variable index. But compare the
\r
2259 following to the code in BIF:
\r
2262 ldb [,s++] 10~ (stored as byte offset)
\r
2263 pshu d 7~ (there's the address)
\r
2264 jmp [,y++] 9~ 32~ compared to 34~
\r
2266 If X is used for the temporary W register as in the indirect threaded
\r
2267 inner interpreter example above, we can get the following, which speaks
\r
2271 clrb 2~ (showing word offset, )
\r
2272 addd 2,x 7~ (byte would be shorter)
\r
2276 Ah, experience. What we have to go through to get it!
\r
2278 The key to FORTH and its dialects is found in ;CODE and DOES>. By
\r
2279 providing both characteristic behaviour and data allocation, FORTH words
\r
2280 (symbols/definitions) are primitive objects. A full object-oriented
\r
2281 language could be generated with FORTH, but then you would probably have
\r
2282 SMALLTALK!. A standard compiling language keeps the symbol table, its
\r
2283 data, and the code that accesses it entirely separate, and wastes a lot
\r
2284 of code space doing so. Professional FORTH systems can strip the symbol
\r
2285 table out of compiled applications, if necessary, but the symbol table
\r
2286 is available at run-time until the programmer is satisfied that his
\r
2287 program is bug-free. Moreover, the programmer has access to the same
\r
2288 library used by the language, which is usually not the case with
\r
2289 compiled languages, even with C.
\r
2291 A careful examination of the overhead in FORTH shows that it is
\r
2292 approximately the same as the overhead in a good C compiler. While it
\r
2293 would appear that constantly moving stuff on and off the stack would be
\r
2294 a hindrance to progress, a second look reveals that the accumulator
\r
2295 bottleneck requires this kind of movement. I wish I had time and
\r
2296 facilities to examine this specific question in relation to a large
\r
2299 I sometimes wonder if management paranoia (PROTECT OUR INTELLECTUAL
\r
2300 PROPERTY!) is the primary reason FORTH, LISP, and SMALLTALK have not
\r
2301 entirely supplanted the compiled languages. If so, why is management
\r
2302 willing to hide, protect, and hang on to code, but not willing to hang
\r
2303 on to the engineers in whose brains the technology really resides? Or
\r
2304 in the converse, if management can see that it is sometimes necessary to
\r
2305 let people go, why can't they see that there are some things that are
\r
2306 not worth the cost of trying to protect their tools from? And why can't
\r
2307 they see that a intellectual property stolen by copying still requires a
\r
2308 large investment in somebody's time to learn to use it? Why doesn't
\r
2309 public domain code get used? Because it costs better than an order of
\r
2310 magnitude more to learn how to use it than it does to get it.
\r
OSDN Git Service
