  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 






                                    
