Chapter 1

An Introduction to P21Forth 1.02

P21Forth 1.02 is an ANS Forth system for the MuP21 microprocessor. It provides the use with a portable and easy to use programming environment that complies with American National Standard X3.215-1994 Forth language specification. P21Forth uses only 16 kilowords of MuP21 memory, but provides boot code, a text interpretter, a Forth compiler, an MuP21 assembler, metacompiler, and over 500 easy to access Forth words.

P21Forth supports colored text and graphics output to a video display, and it also supports a serial or parallel terminal or both. The user may select the type of input and output that they want to use. A terminal or at least a keyboard must be attached to the MuP21 system to use P21Forth.

When P21Forth starts it puts the message P21Forth on the video screen and looks for a parallel or serial keyboard on the input port. If a serial terminal or keyboard is being used P21Forth will try to determine the speed of the attached device. P21Forth reads a `b' character from the serial device and initializes the serial input output routine.

To start P21Forth with a serial keyboard or terminal the user must send a `b' character to the MuP21 system. If all of the bits on the parallel port are set when P21Forth boots it will assume that a parallel keyboard or terminal is attached and start in that mode.

After P21Forth displays the boot message and begins reading the keyboard it will respond to an Enter or Return with the familiar Forth `ok' prompt. This is an indication that the text interpreter has processed a line of text and is ready for a new command.

Press Enter several times and P21Forth should respond with several ok.

The P21Forth language consists of a list of over 500 words that are commands in the language and most can be executed if they are typed on the command line. A user can extend the language by creating new words.

The Forth word WORDS will display the names of all of the words in the Forth dictionary.

Type WORDS and press Enter for P21Forth to display the list of defined words. If you press a key while the list is being displayed it will pause, if you then press the Enter key the display will stop, any other key will restart the list display.


Forth uses a mechanism called a stack to store items. Like a stack of physical items the last item placed on a stack will be on the top, and the first item will be on the bottom. When you remove things from the stack the last item placed on the stack will be the first removed from the top.

Forth uses two stacks, one for data and one for the return addresses of Forth words. These as know as the data stack and the return stack. There are Forth words to manipulate these stacks.


P21Forth uses two dictionaries to store the names of the Forth words, and the code and data associated with those words. There are Forth words to manipulate the name and code dictionaries.


The operation and syntax of Forth is very simple. The syntax is simply that Forth words are separated by spaces. The operation is that words are looked up and found in the dictionary, or are interpreted as a number, or are an error. If you enter a word into the Forth interpreter it will try to look it up and execute the associated code in the dictionary. If the word is not in the dictionary it will then see if it is a number that can be put on the data stack. If it is not in the dictionary and is not a number then it is an error and an error message is generated.

If you type 1 2 3 and press Enter you will place the numbers 1, 2, and 3 on the data stack. The number 3 will be on the top of the stack. If you type a period and press Enter P21 will print the number on the top of the stack. If you type a period again and press Enter again it will print out the next item on the stack. If you attempt to print out more items that you have placed on the stack P21Forth will produce an error message.

Writing a Forth Program

The word (pronounced Colon) is used to define new words in : Forth. If you type
: XDEMO 1 . ; and press Enter, this will define a new Forth word called XDEMO that will place a 1 on the data stack and then print out the value on the stack. The word XDEMO can now by typed on the command line or used in other definitions.

P21Forth will begin using the HEX number base. All numbers will be interpreted and displayed as HEX numbers. The word DECIMAL will change the number base to base 10 numbers. If you type HEX 1234 DECIMAL . Forth will interpret 1234 as a hex number, place it on the stack, and then remove it and print it as a decimal number.

ANS Forth

The ANS Forth standard provides a new widely accepted portable standard for Forth programs. The standard specifices in detail the operation of standard words and also specifies the things that must be documented in order for a system to declare that it is an ANS Forth compliant implementation.

The ANS Forth standard provides information that will be true of all ANS Forth compliant systems. The details of the implementation are provided in some utility words, the user manual, and the source for P21Forth 1.0. (See Appendix 2)

Writing Portable Programs

In order to write portable ANS Forth programs one needs to maintain several programming habits. The most important has to do with addressing units. In ANS Forth memory is addressed in CELLS. A CELL is a unit of memory containing an item the size of one item on the stack. The MuP21 has a 21 bit alu and a 20 bit memory bus. P21Forth is a 20 bit word implementation of ANS Forth. The items on the data and return stacks and in memory CELLS are 20 bits wide in P21Forth. MuP21 is a CELL addressing machine, that is each address of memory contains a 20 bit number or CELL. On a machine with byte addressing a 16 bit Forth would use two bytes per CELL, and a 32 bit Forth would use four bytes per CELL. Forth programmers who have used 16 bit Forths on byte addressing machines have a habit of using 2* to convert between the number of 16 bit items and the number of addressing units (or bytes) to hold them. The problem with this is that on a byte addressing machine a 32 bit Forth would need 4 * to convert between the number of items and the number of byte address units. ANS Forth uses CELL addressing, so it will support portable code. The word CELLS converts a count of items into the addressing number that a system uses. On a 32 bit Forth on a byte addressing machine CELLS would multiply by 4, and on a 16 bit Forth on a byte addressing machine CELLS would multipy by 2. In P21Forth CELLS does nothing. This is because on a word addressing machine CELLS is the same as 1 * which does nothing.

If a program is to be portable one must consider the correct use of the Forth words CELL+, CELL-, and CELLS when dealing with the addresses of stack items stored in memory. Just as 2+ would properly move from the address of one stack item in memory on a byte addressing 16 bit Forth the word 1+ will properly move to the next stack item in memory on a word addressing machine and 4 + would work properly on a byte addressing machine with a 32 bit Forth. This type of code would not be portable on all machines. The correct use of CELL+ rather than 1+ or 2+ or 4 + or whatever can make a program portable on any ANS Forth implementation that also provides for all the specific environmental dependencies of a given program.

For properly addressing characters in memory ANS Forth provides the words CHAR+, and CHARS. These words work like the CELL words, but make character addressing portable across machines.

Consult the ANS Document for more information on portability issues. There are words in P21Forth that are standard ANS Forth words. If a uses sticks to the proper use of these words programs can be portable accross ANS Forth systems. There are also words in P21Forth that are common to implementations of Forth. Finally there are words in the P21Forth implementation that are unique to P21Forth. If you write code that uses words specific to P21Forth then the code will not be portable unless these same words are provided on some different platform.

End of Chapter 1

Return to Table of Contents

Next Chapter