Technical Information


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



Release Specifications

The current kForth release is:

Version: 1.0.14
Last Release Date: 2003-04-19
Systems: Linux, Windows 95/98/NT/2000/XP (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 the FreeBSD and BeOS operating systems (for BeOS, see Todd Nathan's README.beos file for build instructions).


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.
Executing the word ABORT will reset the stack pointers. This procedure should be used to recover from VM errors 5 and 7, and whenever there is a suspicion that the stacks have been corrupted.

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:



Benchmarks and Tests

Versions of standard benchmark programs for measuring kForth execution speed may be found under the directory: examples/benchmarks/.

John Hayes' suite of tests for the core words of an ANS Forth system is available for kForth: tester.4th and core.4th. Tests involving unsupported words such as HERE and , and C, have been commented out, as well as tests involving the BEGIN ... WHILE ... WHILE ... REPEAT ... THEN structure, and some weird variants of CREATE and DOES> usage.



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.




CCRE Home Page

Copyright © 1998--2003 Creative Consulting for Research and Education