Technical Information


  1. Release Specifications
  2. Implementation
    1. ANS Forth Compliance
    2. Threading Model
    3. Signed Integer Division
    4. Floating Point Implementation
    5. Special Features
  3. Benchmarks and Tests
  4. VM Error Codes
  5. Source Code Map
  6. Embedding kForth



Release Specifications

The current kForth release is:

Version: 1.3.1
Last Release Date: 2005-11-08
Systems: Linux, Windows 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 file for build instructions).


Implementation

ANS Forth Compliance

kForth is specified as a subset of the ANS Forth standard, given in DPANS94. Code written for kForth is portable to ANS-compliant Forth systems with the use of trivially defined extensions (see the Special Features section below). The compliance with ANS Forth may be checked using John Hayes' suite of tests for the core words of an ANS Forth system: 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.

Threading Model

kForth is an indirect threaded code (ITC) system. The kForth compiler/interpreter parses the input stream into a vector of pseudo op-codes or Forth Byte Code. Upon execution, the vector of byte codes is passed on to a virtual machine which looks up the execution address of the words and performs either a call or an indirect jump to the next execution address. The type of threading used in the virtual machine is a hybrid of indirect call threading and indirect jump threading. The kForth virtual machine is implemented as a mixture of assembly language, C, and C++ functions. Only the assembly language portion of the virtual machine utilizes indirect jump threading.

Signed Integer Division

kForth versions 1.2.10 and earlier implement symmetric integer division. An alternative form of signed integer division is called floored integer division. Both symmetric and floored division yield identical results when the two operands, dividend and divisor, are either both positive integers or both negative integers. However, when the two operands differ in sign, symmetric and floored integer division can give different results. For example,

Floored Division:-8 3 / . -3 ok

Symmetric Division: -8 3 / . 2 ok

Similarly, the word MOD yields different results on floored and symmetric division systems. Under floored division, MOD is truly a modulus operator (i.e. the result of n1 n2 MOD is a number in the range [0, n2)), while under symmetric division, MOD simply returns a remainder. The following paper provides a discussion of integer division in computing languages: Division and Modulus for Computer Scientists by Daan Leijen.

Floored integer division was guaranteed by the Forth-83 standard. However, the DPANS94 standard revoked this guarantee and allowed system implementors to choose either symmetric or floored integer division. The rationale in revoking a fixed standard was to allow Forth systems to implement whatever form of integer division was best supported by the microprocessor hardware. Most microprocessors which provide signed integer division implement symmetric division. In kForth, the original rationale for using symmetric division was simply to maintain consistency with the GNU C implementation, which mandates the use of symmetric integer division per the ISO C99 standard (the symmetric version of MOD corresponds to the % operator in C). In general, floored division is considered by computer scientists and mathematicians to be the more useful form of signed integer division. An informative discussion on floored versus symmetric division is given in the following article: Signed Integer Division by Robert L. Smith.

A significant problem with the DPANS94 standard is that, in practice, implementors of ANS-compliant Forth systems for a single hardware platform such as Intel x86 have chosen to use different forms of division. Consider the behavior of the Forth systems below, all running under Linux on a Intel PII:

gforth:   -8 3 MOD .  -2 ok
pfe:      -8 3 MOD .   1 ok
kforth:   -8 3 MOD .  -2 ok
iforth:   -8 3 MOD .  -2 ok
bigforth: -8 3 MOD .   1 ok
Therefore, a Forth program using signed integer division words (/ MOD /MOD */MOD) may produce different outputs under two different ANS-compliant Forth systems. The DPANS94 standard addresses the portability issue by calling for use of the explicit floored and symmetric division words FM/MOD and SM/REM whenever it is important to explicitly specify the type of division. However, it is highly likely that Forth programmers will casually use signed integer division words such as MOD without always remembering the portability issue. It is anticipated that future versions of kForth (> 1.2.10) will provide a method of switching between floored and symmetric division.

Floating Point Implementation

The ANS Forth specification allows floating point numbers to be stored either on the data stack or on a separate floating point stack. kForth uses the data stack for holding floating point numbers. Even though many current Forth systems for PCs feature a separate floating point stack, the rationale for using the data stack for floating point operations in kForth was to allow legacy code written for earlier Forth systems (in particular the Forths from Laboratory Microsystems Inc.) to run without significant modifications under kForth. In kForth, a floating point number on the stack occupies two cells. Thus, under 32-bit Windows or Linux, floating point numbers are 64-bit double-precision numbers (equivalent to C's double).

Special Features

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 in the ftp site under /software/kforth/examples/benchmarks.



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.
  16. ENDOF without matching OF.
  17. ENDCASE without matching CASE.
  18. Cannot open file.
  19. Address outside of stack space.
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.

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
fast/ForthCompiler-fast.cpp
fast/ForthVM-fast.cpp
fast/kforth-fast.cpp
fast/vm-fast.s
fast/vmc-fast.c
fast/ForthCompiler.h
fast/ForthVM.h
fast/fbc.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--2005 Creative Consulting for Research and Education