Technical Information

1. Release Specifications
2. VM Error Codes
3. Implementation
4. Benchmarks
5. Source Code Map
6. Embedding kForth

Release Specifications

The current kForth release is:

Version: 1.0.11
Last Release Date: 02-10-2002
Systems: Linux, Windows 95/98/NT/2000 (on ix86 and compatible PCs only)

In general new releases for Linux and Windows are made available simultaneously on our website. Thus the documentation for the kForth dictionary is valid for all versions, unless specially noted. Some releases may contain experimental words which are not fully implemented or debugged. However, such words will not be documented in the user's guide and should not be used until they appear in the dictionary section of the user's guide. The Linux version of kforth is also reported to work under FreeBSD.

VM Error Codes

Non-zero return codes from the virtual machine (VM) indicate the following conditions:

1. Value on the stack did not have type addr.
2. Value on the stack did not have type ival.
3. Value on the stack has unknown type.
4. Division by zero.
5. Return stack has been corrupted.
6. Invalid kForth op-code encountered.
7. Stack underflow.
8. Return code for QUIT (not seen by user).
9. Attempted to re-ALLOT memory for a word.
10. Failed on CREATE (bad word name).
11. End of string not found.
12. No matching DO.
13. No matching BEGIN.
14. ELSE without matching IF.
15. THEN without matching IF.

Implementation

The kForth compiler/interpreter parses the input stream into a vector of pseudo op-codes or Forth Byte Code. The vector of codes is passed on to the virtual machine which executes the codes. The kForth virtual machine is implemented as a mixture of assembly language, C, and C++ functions. Special features of kForth are described in a two-part article in Forthwrite magazine, issues 116 and 117.These features are:

• The kForth dictionary is dynamically allocated as new definitions are added. Thus kForth does not implement a monolithic, fixed size dictionary, but can use as much memory as provided by the host operating system. Several side effects result from using dynamic memory allocation to grow the dictionary:
  
  
  • There is no HERE address in kForth.
  • There is no , (comma operator) in kForth.
  • There is no C, operator in kForth.
  
  Owing to the fact that HERE does not exist, the word ALLOT not only allocates the requested amount of memory, but also has the non-standard behavior that it assigns the address of the new memory region to the parameter field address (PFA) of the last defined word. In kForth, the use of ALLOT must always be preceeded by the use of CREATE. A variant of ALLOT, named ?ALLOT is also provided. ?ALLOT has the same behavior as ALLOT plus it returns the start address of the dynamically allocated region on the parameter stack. ?ALLOT has the following equivalent definition under ANS Forth:
  
  : ?ALLOT ( u -- a ) HERE SWAP ALLOT ;

?ALLOT is particularly useful in writing defining words in the absence of HERE and the comma operators. For example, to write your own integer constant defining word:
  
  : CONST ( n -- ) CREATE 4 ?ALLOT ! DOES> @ ;
  
  or to write an address constant defining word (see below):
  
  : PTR ( a -- ) CREATE 4 ?ALLOT ! DOES> A@ ;
  
  
• kForth maintains type stacks corresponding to both the data and return stacks. The type stacks contain a type code for each corresponding data stack cell or return stack cell. This allows kForth to perform some rudimentary type checking, for example when an address is being accessed kForth verifies that the value's type is that of an address. Address values that are stored in variables must be retrieved with the word A@ instead of @ so that the type can be validated. Code written for kForth may be ported to other ANS Forth implementations by defining A@ as follows:
  
  : A@ @ ;
  
  
• Floating point numbers are pushed onto the data stack --- a separate floating point stack is not used. The ANS specification allows either method. A floating point number on the stack occupies two cells.
  
  
• Unlike a conventional Forth interpreter which executes each token as it is interpreted, kForth continues to build up a vector of byte codes, until a keyword or end of line in the input stream necessitates execution. Deferred execution in interpreter mode is implemented by extending the normal concept of precedence in Forth. Instead of a single precedence-bit associated with each word, kForth uses a precedence-byte having two significant bits to describe the behavior of each word in both compiled and interpreted modes. Thus, a word may have one of four possible precedence values:
  
  
  1. not IMMEDIATE, DEFERRED
     
  2. IMMEDIATE, DEFERRED
     
  3. not IMMEDIATE, NONDEFERRED
     
  4. IMMEDIATE, NONDEFERRED
     
  
  
  To understand the execution behavior of a word in each of these states, it is helpful to view a table of execution modes for each precedence value and for the two compilation states: interpret and compile. We define the following execution modes:
  
  
  • E0 -- no execution, the opcode for the word is compiled into the opcode vector.
    
  • E1 -- execute current opcode vector up to and including current opcode.
    
  • E2 -- execute only current opcode and remove it from the opcode vector.
  
  
  

  Precedence	Interpret	Compile
  0	E0	E0
  1	E2	E2
  2	E1	E0
  3	E1	E2

  
  
  The ability to defer execution in interpreter mode allows "one-liners" to be executed from the kForth prompt without having to define a word. For example, the following line can be typed directly at the kForth prompt:
  
  10 0 do i . loop
  Ordinary Forth interpreters do not allow do-loop, begin-while-repeat, and if-then structures to occur outside of word definitions. kForth can interpret and execute such structures as long as they are completed on a single line of input.
  
  
  kForth can be started up in debug mode using the command line switch -D. Compiled op-codes and other debugging information are displayed in this mode. It is useful primarily for programmers interested in extending and debugging their own versions of kForth.

Benchmarks

Versions of standard benchmark programs for measuring kForth execution speed may be found in the ftp site under /software/kforth/examples/benchmarks.

Source Code Map

Source code for kForth consists of the following C++, C, and assembly language files:

kforth.cpp
ForthCompiler.cpp
ForthVM.cpp
vmc.c
vm.s
fbc.h
ForthCompiler.h
ForthVM.h

The source code is made available to users under the GNU General Public License. The Linux version is provided as source code only and must be built locally on the user's machine (see installation). Under Linux, the standard GNU assembler, GNU C and C++ compilers, and the C++ Standard Template Library (STL) are required to build the executable. The Windows 95/98/NT console application was built using the free Cygwin port of the GNU development tools.

Embedding kForth

The file kforth.cpp serves as a skeleton C++ program to illustrate how the kForth compiler and virtual machine may be embedded in a standalone program. XYPLOT for Linux is a more complex GUI program which embeds kForth to allow user extensibility. The file xyplot.cpp shows how to set up hooks for calling C++ functions in the host program from the embedded kForth interpreter and vice-versa.

The rest of this section is being written.