Wednesday, March 28, 2018

Exhaustive documentation and deconstruction of original FORTH

ANNOTATING AND DECONSTRUCTING FORTH

One aspect of FORTH on the 1130 makes the task of investigating and deconstructing the behavior easy. The assembler code is always loaded starting at hex 0900 and that means the locations of the dictionary entries are always the same for the FORTH statements executed off the disk file as part of FORTH bootup.

I dug through core memory to extract the locations of the dictionary entries once FORTH typed its HI THERE prompt for user input. Every dictionary entry has a fixed part, four cells that are sequentially arranged from the built in primitives up to the final word in the dictionary. In addition, there is a variable part that is arranged beginning at hex 1A00 and growing upwards.

The fixed entry has the first four characters of the name of this entry, an address to execute when this word is encountered, and a parameter cell that is used for some but not all types of words. Notice that words are only defined by the first four characters, thus CHARACTER and CHARSUM will refer to the same entry in the dictionary. 

Entries that are defined by : and ; bracketing a string of words will establish a dictionary entry in the name of the first word, then in the variable entry will store the remaining words, separated by blanks, up to an including the trailing ; character. 

Entries that are defined by an initial OPERATION word are stored as an entry under the next word. The remaining words are compiled immediately into 1130 machine instructions, set up as a callable subroutine. Subroutines are entered using the BSI instruction, which stores the return address in the first cell and then executes for a while before branching back to the return address. 

If the words being compiled (in an OPERATION block, called a CODE block in more recent FORTH) are definitions that were saved as text by :;, then they are now compiled. This proceeds recursively if an entry in turn references another regular definition, or calling the subroutine if the entry in turn references some CODE/OPERATION compiled code.

I can see the 1130 instructions and data that are set up in the code blocks, helping me to understand how it all works. For the text saved entries (those defined with :;) I have to see that entry used in a code block before it is actually compiled. I can either find a code block which referred to a text definition, seeing what was generated from it, or I can set up my own code block as a new entry after the user prompt. My code block can refer to a text entry, causing it to be compiled. 

Using these tricks, I very slowly and painfully built up an annotation of every FORTH statement, showing what it produced. There are two results of these statements - changes to the stack and additions to the variable dictionary -- so I extended normal FORTH shorthand for documentation.

It is normal for a FORTH definition to show what must be on the stack before execution and what is left on the stack afterwards. For example, (n m -- c) means n is on the top of the stack and m is the entry below it. They are both consumed and a result c is left on the stack after we finish execution.

I chose to add a new shorthand for the output to the variable dictionary entry as var: (a, b, c, . . . ) where a, etc are what is added to the variable entry. I discuss any unusual aspects in the text below that shorthand. As an example, the statement:
   :L 400 INST;               (n -- ) var: (n OR 0400)
takes a cell on the stack which is the basis for an instruction, ORs that with 0400 to produce an instruction that is in 1130 long format, and sticks that instruction in the variable stack. If this is called with C000 in the stack, the basis for a load instruction, then we will have C400 on the variable stack when the word L is executed. 

Later in the disk file of FORTH commands, very sophisticated operations are built from these more basic verbs. My documentation will shift to focus upon the high level behavior, although I will still retain my stack and variable dictionary shorthands. 

It will take me several more days before I have the entire file interpreted. At that point I should be able to use it properly. 

No comments:

Post a Comment