1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
<html>
<head>
<title>kForth Technical Information</title>
</head>
<body bgcolor=white>
<h2><img src="kforth.gif"> Technical Information</h2><br>
<ol>
<li><a href="#Release Specifications">Release Specifications</a>
<li><a href="#VM Error Codes">VM Error Codes</a>
<li><a href="#Implementation">Implementation</a>
<li><a href="#Source Code Map">Source Code Map</a>
<li><a href="#Embedding kForth">Embedding kForth</a>
</ol>
<br><br>
<hr>
<h3><a name="Release Specifications"></a>Release Specifications</h3>
<p>
The current kForth release is:<br><br>
<i>Version:</i> 1.0<br>
<i>Last Release Date:</i> 8-8-2000<br>
<i>Systems: </i>Linux, Windows 95/98/NT (on ix86 and compatible PCs only)<br>
<br>
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 <a href="kforth3.html">dictionary</a> section
of the user's guide. The Linux version of kforth is also reported to work
under FreeBSD.<br>
<br>
<hr>
<h3><a name="VM Error Codes"></a>VM Error Codes</h3>
<p>
Non-zero return codes from the virtual machine (VM) indicate the
following conditions:<br>
<ol>
<li>Value on the stack did not have type <code>addr</code>.
<li>Value on the stack did not have type <code>ival</code>.
<li>Value on the stack has unknown type.
<li>Division by zero.
<li>Return stack has been corrupted.
<li>Invalid kForth op-code encountered.
<li>Stack underflow.
<li>Return code for <code>QUIT</code> (not seen by user).
<li>Attempted to re-<code>ALLOT</code> memory for a word.
<li>Failed on <code>CREATE</code> (bad word name).
<li>End of string not found.
<li>No matching <code>DO</code>.
<li>No matching <code>BEGIN</code>.
<li><code>ELSE</code> without matching <code>IF</code>.
<li><code>THEN</code> without matching <code>IF</code>.
</ol>
Executing the word <code>ABORT</code> 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.<br>
<hr>
<h3><a name="Implementation"></a>Implementation</h3>
<p>
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 <i>virtual machine</i>
which executes the codes. The kForth virtual machine is implemented
as a mixture of assembly language, C, and C++ functions.
Some implementation dependent features are:
<ul>
<li> The kForth dictionary is <i>dynamically allocated</i>
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:<br><br>
<ul>
<li>There is no <code>HERE</code> address in kForth.
<li>There is no <code>,</code> (comma operator) in kForth.
<li>There is no <code>C,</code> operator in kForth.
</ul><br>
Owing to the fact that <code>HERE</code> does not exist,
the word <code>ALLOT</code> 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 <i>parameter field address</i> (PFA) of the last defined word.
In kForth, the use of <code>ALLOT</code> must always be preceeded
by the use of <code>CREATE</code>. A variant of <code>ALLOT</code>,
named <code>?ALLOT</code> is also provided. <code>?ALLOT</code> has the
same behavior as <code>ALLOT</code> plus it returns the
start address of the dynamically allocated region on the parameter
stack. <code>?ALLOT</code> has the following equivalent definition
under ANS Forth:<br>
<br>
<center>
<code>: ?ALLOT ( u -- a ) HERE SWAP ALLOT ; </code>
</center><br>
<br>
<code>?ALLOT</code> is particularly useful in writing <i>defining words</i>
in the absence of <code>HERE</code> and the comma operators. For
example, to write your own integer constant defining word:<br>
<br>
<center>
<code>: CONST ( n -- ) CREATE 4 ?ALLOT ! DOES> @ ; </code>
</center><br>
<br>
or to write an address constant defining word (see below):<br>
<br>
<center>
<code>: PTR ( a -- ) CREATE 4 ?ALLOT ! DOES> A@ ; </code>
</center><br><br>
<li> kForth maintains <i>type stacks</i> 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
<b>A@</b> instead of <b>@</b> so that the type can be validated.
Code written for kForth may be ported to other ANS Forth
implementations by defining <code>A@</code> as follows:<br>
<br>
<center>
<code>: A@ @ ;</code>
</center>
<br><br>
<li> Floating point numbers are pushed onto the <i>data stack</i>
--- a separate floating point stack is not used. The ANS specification
allows either method. A floating point number on the stack
occupies two cells.<br>
<br>
<li> 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. <i>Deferred execution</i>
in interpreter mode is implemented by extending the normal concept
of <i>precedence</i> in Forth. Instead of a precedence-bit
associated with each word, kForth uses a precedence-<i>byte</i>
to describe the behavior of each word in both compiled and
interpreted modes. 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:<br>
<br>
<center>
<code>10 0 do i . loop</code>
</center><br>
Ordinary Forth interpreters do not allow <code>do-loop</code>,
<code>begin-while-repeat</code>, and <code>if-then</code> 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.<br>
<br>
<li> kForth can be started up in <i>debug mode</i> using the
command line switch <code>-D</code>. 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.
</ul>
</p>
<br><hr>
<h3><a name="Source Code Map"></a>Source Code Map</h3>
<p>
Source code for kForth consists of the following C++, C, and assembly
language files:<br><br>
<code>
kforth.cpp<br>
ForthCompiler.cpp<br>
ForthVM.cpp<br>
vmc.c<br>
vm.s<br>
fbc.h<br>
ForthCompiler.h<br>
ForthVM.h<br>
</code><br>
The source code is made available to users under the
<a href="http://www.gnu.org/copyleft/gpl.html">GNU General
Public License</a>. The Linux version is provided as
source code only and must be built locally on the user's machine
(see <a href="kforth1a.html#Installation under Linux">installation</a>).
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
<a href="http://cygwin.com">Cygwin</a> port of the GNU
development tools.
</p>
<br><hr>
<h3><a name="Embedding kForth"></a>Embedding kForth</h3>
<p>
The file <code>kforth.cpp</code> 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.
<br><br>
The rest of this section is being written.<br><br>
<hr>
<a href="kforth4.html"><img src="left.gif"></a><br><br>
<a href="http://www.ccreweb.org">CCRE Home Page</a>
<br><br>
Copyright © 1998--2000 Creative Consulting for Research and Education<br>
</body>
</html>
|
