This documentation is dated 1979:may. Chapter 6.0 was considered out of date 1980:NOV. OCR-ed by A.van der Horst, DFW, The Netherlands (2000:MAR) Correction of typo's (some original) and slight changes to the layout are the only changes. fig-FORTH INSTALLATION MANUAL 1.0 INTRODUCTION 2.0 DISTRIBUTION 3.0 MODEL ORGANIZATION 4.0 INSTALLATION 5.0 MEMORY MAP 6.0 DOCUMENTATION SUMMARY 1.0 INTRODUCTION The fig-FORTH implementation project occurred because a key group of Forth fanciers wished to make this valuable tool available on a personal computing level. In June of 1978, we gathered a team of nine systems level programmers, each with a particular target computer. The charter of the group was to translate a common model of Forth into assembly language listings for each computer. It was agreed that the group's work would be distributed in the public domain by FIG. This publication series is the conclusion of the work. 2.0 DISTRIBUTION All publications of the Forth Interest Group are public domain. They may be further reproduced and distributed by inclusion of this credit notice: This publication has been made available by the Forth Interest Group, P. O. Box 1105, San Carlos, Ca 94070 We intend that our primary recipients of the Implementation Project be computer users groups, libraries, and commercial vendors. We expect that each will further customize for particular computers and redistribute. No restrictions are placed on Cost, but we expect faithfulness to the model. FIG does not intend to distribute machine readable versions, as that entails customization, revision, and customer support better reserved for commercial vendors. Of course, another broad group of recipients of the work is the community of personal computer users. We hope that our publications will aid in the use of Forth and increase the user expectation of the performance of high level computer languages. 3.0 MODEL ORGANIZATION The fig-FORTH model deviates a bit from the usual loading method of Forth. Existing systems load about 2k bytes in object form and then self-compile the resident system (6 to 8 k bytes). This technique allows customization within the high level portion, but is impractical for new implementors. Our model has 4 to 5 k bytes written as assembler listings. The remainder may be compiled typing in the Forth high-level source, by more assembly source, or by disc compilation. This method enhances transportability, although the larger portion in assembly code entails more effort. About 8k bytes of memory is used plus 2 to 8k for workspace. 3.1 MODEL OVER-VIEW The model consists of 7 distinct areas. They occur sequentially from low memory to high. Boot-up parameters Machine code definitions High level utility definitions Installation dependent code High level definitions System tools (optional) RAM memory workspace 3.2 MODEL DETAILS Boot-up Parameters This area consists of 34 bytes containing a jump to the cold start, jump to the warm re-start and initial values for user variables and registers. These values are altered as you make permanent extensions to your installation. Machine Code Definitions This area consists of about 600 to 800 bytes of machine executable code in the form of Forth word definitions. Its purpose is to convert your computer into a standard Forth stack computer. Above this code, the balance of Forth contains a pseudo-code compiled of "execution-addresses" which are sequences of the machine address of the "code-fields" of other Forth definitions. All execution ultimately refers to the machine code definitions. High-level Utility Definitions These are colon-definitions, user variables, constants, and variables that allow you to control the "Forth stack computer". They comprise the bulk of the system, enabling you to execute and compile from the terminal. If disc storage (or a RAM simulation of disc) is available, you may also execute and compile from this facility. Changes in the high-level area are infrequent. They may be made thru the assembler source listings. Installation Dependent Code This area is the only portion that need change between different installations of the same computer cpu. There are four code fragments: (KEY) Push the next ascii value (7 bits) from the terminal keystroke to the computation stack and execute NEXT. High 9 bits are zero. Do not echo this character, especially a control character. (EMIT) Pop the computation stack (16 bit value). Display the low 7 bits on the terminal device, then execute NEXT. Control characters have their natural functions. (?TERMINAL) For terminals with a break key, wait till released and push to the computation stack 0001 if it was found depressed; otherwise 0000. Execute NEXT. If no break key is available, sense any key depression as a break (sense but don't wait for a key). If both the above are unavailable, simply push 0000 and execute NEXT. (CR) Execute a terminal carriage return and line feed. Execute NEXT. When each of these words is executed, the interpreter vectors from the definition header to these code sequences. On specific implementations it may be necessary to preserve certain registers and observe operating system protocols. Understand the implementors methods in the listing before proceeding! R/W This colon-definition is the standard linkage to your disc. It requests the read or write of a disc sector. It usually requires supporting code definitions. It may consist of self-contained code or call ROM monitor code. When R/W is assembled, its code field address is inserted once in BLOCK and once in BUFFER. An alternate version of R/W is included that simulates disc storage in RAM. If you have over 16 k bytes this is practical for startup and limited operation with cassette. High-level Definitions The next section contains about 30 definitions involving user interaction: compiling aids, finding, forgetting, listing, and number formating. These definitions are placed above the installation dependent code to facilitate modification. That is, once your full system is up, you may FORGET part of the high-level and re-compile altered definitions from disc. System Tools A text editor and machine code assembler are normally resident. We are including a sample editor and hope to provide Forth assemblers. The editor is compiled from the terminal the first time, and then used to place the editor and assembler source code on disc. It is essential that you regard the assembly listing as just a way to get Forth installed on your system. Additions and changes must be planned and tested at the usual Forth high level and then the assembly routines updated. Forth work planned and executed only at an assembly level tends to be non-portable, and confusing. RAM Workspace For a single user system, at least 2k bytes must be available above the compiled system (the dictionary). A 16k byte total system is most typical. The RAM workspace contains the computation and return stacks, user area, terminal input buffer, disc buffer and compilation space for the dictionary. 4.0 INSTALLATION We see the following methods of getting a functioning fig-FORTH system: 1. Buy loadable object code from a vendor who has customized. 2. Obtain an assembly listing with the installation dependent code supplied by the vendor. Assemble and execute. 3. Edit the FIG assembly listing on your system, re-write the I-O routines, and assemble. 4. Load someone else's object code up to the installation dependent code. Hand assemble equivalents for your system and poke in with your monitor. Begin execution and type in (self-compile) the rest of the system. This takes about two hours once you under stand the structure of Forth (but that will take much more time!). Let us examine Step 3, above, in fuller detail. If you wish to bring up Forth only from this model, here are the sequential steps: 4.1 Familiarize yourself with the model written in Forth, the glossary, and specific assembly listings. 4.2 Edit the assembly listings into your system. Set the boot-up parameters at origin offset 0A, 0B (bytes) to 0000 (warning=00). 4.3 Alter the terminal support code (KEY, EMIT, etc,) to match your system. Observe register protocol specific to your implementation! 4.4 Place a break to your monitor at the end of NEXT, just before indirectly jumping via register W to execution. W is the Forth name for the register holding a code field address, and may be differently referenced in your listings. 4.5 Enter the cold start at the origin. Upon the break, check that the interpretive pointer IP points within ABORT and W points to SP!. If COLD is a colon-definition, then the IP has been initialized on the way to NEXT and your testing will begin in COLD. The purpose of COLD is to initialize IP, SP, RP, VP, and some user variables from the start-up parameters at the origin. 4.6 Continue execution one word at a time. Clever individuals could write a simple trace routine to print IP, W, SP, RP and the top of the stacks. Run in this single step mode until the greeting message is printed. Note that the interpretation is several hundred cycles to this stage! 4.7 Execution errors may be localized by observing the above pointers when a crash occurs. 4.8 After the word QUIT is executed (incrementally), and you can input a "return" key and get OK printed, remove the break. You may have some remaining errors, but a reset and examination of the above registers will again localize problems. 4.9 When the system is interpreting from the keyboard, execute EMPTY-BUFFERS to clear the disc buffer area. You may test the disc access by typing: 0 BLOCK 64 TYPE This should bring sector zero from the disc to a buffer and type the first 64 characters. This sector usually contains ascii text of the disc directory. If BLOCK (and R/W) doesn't function--happy hunting! 5.0 If your disc driver differs from the assembly version, you must create your own R/W. This word does a range check (with error message), modulo math to derive sector, track, and drive and passes values to a sector-read and sector-write routine. RAM DISC SIMULATION If disc is not available, a simulation of BLOCK and BUFFER may be made in RAM. The following definitions setup high memory as mass storage. Referenced 'screens' are then brought to the 'disc buffer' area. This is a good method to test the start-up program even if disc may be available. HEX 4000 CONSTANT LO ( START OF BUFFER AREA ) 6800 CONSTANT HI ( 10 SCREEN EQUIVALENT ) : R/W >R ( save boolean ) B/BUF * LO + DUP HI > 6 ?ERROR ( range check ) R> IF ( read ) SWAP ENDIF B/BUF CMOVE ; Insert the code field address of R/W into BLOCK and BUFFER and proceed as if testing disc. R/W simulates screens 0 thru 9 when B/BUF is 128, in the memory area $4000 thru $6BFF. fig-FORTH VARIABLE NAME FIELD A major FIG innovation in this model, is the introduction of variable length definition names in compiled dictionary entries. Previous methods only saved three letters and the character count. The user may select the letter count saved, up to the full natural length. See the glossary definition for WIDTH. In this model, the following conventions have been established. 1. The first byte of the name field has the natural character count in the low 5 bits. 2. The sixth bit = 1 when smudged, and will prevent a match by (FIND). 3. The seventh bit = 1 for IMMEDIATE definitions; it is called the precedence bit. 4. The eighth or sign bit is always = 1. 5. The following bytes contain the names' letters, up to the value in WIDTH. 6. In the byte containing the last letter saved, the sign bit = 1. 7. In word addressing computer, a name may be padded with a blank to a word boundary. The above methods are implemented in CREATE. Remember that -FIND uses BL WORD to bring the next text to HERE with the count preceeding. All that is necessary, is to limit by WIDTH and toggle the proper delimiting bits. 5.0 MEMORY MAP The following memory map is broadly used. Specific installations may require alterations but you may forfeit functions in future FIG offerings. The disc buffer area is at the upper bound of RAM memory. It is comprised of an integral number of buffers, each B/BUF+4 bytes. B/BUF is the number of bytes read from the disc, usually one sector. B/BUF must be a power of two (64, 128, 256, 512 or 1024). The constant FIRST has the value of the address of the start of the first buffer. LIMIT has the value of the first address beyond the top buffer. The distance between FIRST and LIMIT must be N*(B/BUF+4) bytes. This N must be two or more. Constant B/SCR has the value of the number of buffers per screen; i.e. 1024 / B/BUF. The user area must be at least 34 bytes; 48 is more appropriate. In a multi-user system, each user has his own user area, for his copy of system variables. This method allows reentrant use of the Forth vocabulary. The terminal input buffer is decimal 80 bytes (the hex 50 in QUERY) plus 2 at the end. If a different value is desired, change the limit in QUERY. A parameter in the boot-up literals locates the address of this area for TIB. The backspace character is also in the boot-up origin parameters. It is universally expected that "rubout" is the backspace. The return stack grows downward from the user area toward the terminal buffer. Forty-eight bytes are sufficient. The origin is in R0 (R-zero) and is loaded from a boot-up literal. The computation stack grows downward from the terminal buffer toward the dictionary which grows upward. The origin of the stack is is in variable S0 (S-zero) and is loaded from a boot-up literal. After a cold start, the user variables contain the addresses of the above memory assignments. An advanced user may relocate while the system is running. A newcomer should alter the startup literals and execute COLD. The word +ORIGIN is provided for this purpose. +ORIGIN gives the address byte or word relative to the origin depending on the computer addressing method. To change the backspace to control H type: HEX 08 0E +ORIGIN ! ( byte addresses) 6.0 DOCUMENTATION SUMMARY The following manuals are in print: Caltech FORTH Manual, an advanced manual with internal details of Forth. Has Some implementation peculiarities. Approx. $6.50 from the Caltech Book Store, Pasadena, CA. Kitt Peak Forth Primer, 520.00 postpaid from the Forth Interest Group, P. O. Box 1105, San Carlos, CA 94070. microFORTH Primer, $15.00 Forth, Inc. 815 Manhattan Ave. Manhattan Beach, CA 90266 Forth Dimensions, newsletter of the Forth Interest Group, $5.00 for 6 issues including membership. F-I-G. P.O. Box 1105, San Carlos, CA. 94070