/* A sometimes minimal FORTH compiler and tutorial for Linux / i386 systems. -*- asm -*-
By Richard W.M. Jones <rich@annexia.org> http://annexia.org/forth
+ This is PUBLIC DOMAIN (see public domain release statement below).
+ $Id: jonesforth.S,v 1.19 2007-09-08 22:51:28 rich Exp $
gcc -m32 -nostdlib -static -Wl,-Ttext,0 -o jonesforth jonesforth.S
-
+*/
+ .set JONES_VERSION,19
+/*
INTRODUCTION ----------------------------------------------------------------------
FORTH is one of those alien languages which most working programmers regard in the same
Also I used this document (http://ftp.funet.fi/pub/doc/IOCCC/1992/buzzard.2.design) which really
defies easy explanation.
+ PUBLIC DOMAIN ----------------------------------------------------------------------
+
+ I, the copyright holder of this work, hereby release it into the public domain. This applies worldwide.
+
+ In case this is not legally possible, I grant any entity the right to use this work for any purpose,
+ without any conditions, unless such conditions are required by law.
+
SETTING UP ----------------------------------------------------------------------
Let's get a few housekeeping things out of the way. Firstly because I need to draw lots of
strings (or rather it used to, but the developers removed it!) so I've abused the syntax
slightly to make things readable. Ignore these warnings.
+ If you want to run your own FORTH programs you can do:
+
+ ./jonesforth < myprog.f
+
+ If you want to load your own FORTH code and then continue reading user commands, you can do:
+
+ cat myfunctions.f - | ./jonesforth
+
ASSEMBLER ----------------------------------------------------------------------
(You can just skip to the next section -- you don't need to be able to read assembler to
THE DICTIONARY ----------------------------------------------------------------------
- In FORTH as you will know, functions are called "words", as just as in other languages they
+ In FORTH as you will know, functions are called "words", and just as in other languages they
have a name and a definition. Here are two FORTH words:
: DOUBLE DUP + ; \ name is "DOUBLE", definition is "DUP +"
You shoud be able to see from this how you might implement functions to find a word in
the dictionary (just walk along the dictionary entries starting at LATEST and matching
- the names until you either find a match or hit the NULL pointer at the end of the dictionary),
+ the names until you either find a match or hit the NULL pointer at the end of the dictionary);
and add a word to the dictionary (create a new definition, set its LINK to LATEST, and set
LATEST to point to the new word). We'll see precisely these functions implemented in
assembly code later on.
and so on. How would a function, say 'f' above, be compiled by a standard C compiler?
Probably into assembly code like this. On the right hand side I've written the actual
- 16 bit machine code.
+ i386 machine code.
f:
CALL a E8 08 00 00 00
%esi -> 1C 00 00 00
2C 00 00 00
- The all-important x86 instruction is called LODSL (or in Intel manuals, LODSW). It does
+ The all-important i386 instruction is called LODSL (or in Intel manuals, LODSW). It does
two things. Firstly it reads the memory at %esi into the accumulator (%eax). Secondly it
increments %esi by 4 bytes. So after LODSL, the situation now looks like this:
| addr of DOUBLE ---------------> +------------------+
+------------------+ %eax -> | addr of DOCOL |
%esi -> | addr of DOUBLE | +------------------+
- +------------------+ | addr of DUP -------------->
+ +------------------+ | addr of DUP |
| addr of EXIT | +------------------+
+------------------+ | etc. |
- First, the call to DOUBLE causes DOCOL (the codeword of DOUBLE). DOCOL does this: It
+ First, the call to DOUBLE calls DOCOL (the codeword of DOUBLE). DOCOL does this: It
pushes the old %esi on the return stack. %eax points to the codeword of DOUBLE, so we
just add 4 on to it to get our new %esi:
| addr of DOUBLE ---------------> +------------------+
top of return +------------------+ %eax -> | addr of DOCOL |
stack points -> | addr of DOUBLE | + 4 = +------------------+
- +------------------+ %esi -> | addr of DUP -------------->
+ +------------------+ %esi -> | addr of DUP |
| addr of EXIT | +------------------+
+------------------+ | etc. |
+--|------+---+---+---+---+------------+
| LINK | 3 | D | U | P | code_DUP ---------------------> points to the assembly
+---------+---+---+---+---+------------+ code used to write DUP,
- ^ len codeword which is ended with NEXT.
+ ^ len codeword which ends with NEXT.
|
LINK in next word
NEXT
defcode "4+",2,,INCR4
- addl $4,(%esp) // increment top of stack
+ addl $4,(%esp) // add 4 to top of stack
NEXT
defcode "4-",2,,DECR4
- subl $4,(%esp) // decrement top of stack
+ subl $4,(%esp) // subtract 4 from top of stack
NEXT
defcode "+",1,,ADD
defcode "-",1,,SUB
pop %eax // get top of stack
- subl %eax,(%esp) // and subtract if from next word on stack
+ subl %eax,(%esp) // and subtract it from next word on stack
NEXT
defcode "*",1,,MUL
_Z
S0 Stores the address of the top of the parameter stack.
R0 Stores the address of the top of the return stack.
+ VERSION Is the current version of this FORTH.
*/
defvar "STATE",5,,STATE
defvar "_Z",2,,TZ
defvar "S0",2,,SZ
defvar "R0",2,,RZ,return_stack
+ defvar "VERSION",7,,VERSION,JONES_VERSION
/*
RETURN STACK ----------------------------------------------------------------------
and compiling code, we might be reading words to execute, we might be asking for the user
to type their name -- ultimately it all comes in through KEY.
- The implementation of KEY uses an input buffer so a certain size (defined at the end of the
+ The implementation of KEY uses an input buffer of a certain size (defined at the end of the
program). It calls the Linux read(2) system call to fill this buffer and tracks its position
in the buffer using a couple of variables, and if it runs out of input buffer then it refills
it automatically. The other thing that KEY does is if it detects that stdin has closed, it
So if DOUBLE is defined in the dictionary, then WORD DOUBLE FIND returns the following pointer:
- pointer to this
+ pointer to this
|
|
V
/*
FIND returns the dictionary pointer, but when compiling we need the codeword pointer (recall
- that FORTH definitions are compiled into lists of codeword pointers).
+ that FORTH definitions are compiled into lists of codeword pointers). The standard FORTH
+ word >CFA turns a dictionary pointer into a codeword pointer.
+
+ The example below shows the result of:
- In the example below, WORD DOUBLE FIND >CFA
+ WORD DOUBLE FIND >CFA
FIND returns a pointer to this
| >CFA converts it to a pointer to this
that is not true in most FORTH implementations where they store a back pointer in the definition
(with an obvious memory/complexity cost). The reason they do this is that it is useful to be
able to go backwards (codeword -> dictionary entry) in order to decompile FORTH definitions.
+
+ What does CFA stand for? My best guess is "Code Field Address".
*/
defcode ">CFA",4,,TCFA
Now we'll talk about how FORTH compiles words. Recall that a word definition looks like this:
- : DOUBLE DUP + ;
+ : DOUBLE DUP + ;
and we have to turn this into:
LATEST points here points to codeword of DUP
There are several problems to solve. Where to put the new word? How do we read words? How
- do we define : (COLON) and ; (SEMICOLON)?
+ do we define the words : (COLON) and ; (SEMICOLON)?
FORTH solves this rather elegantly and as you might expect in a very low-level way which
- allows you to change how the compiler works in your own code.
+ allows you to change how the compiler works on your own code.
- FORTH has an interpreter function (a true interpreter this time, not DOCOL) which runs in a
+ FORTH has an INTERPRETER function (a true interpreter this time, not DOCOL) which runs in a
loop, reading words (using WORD), looking them up (using FIND), turning them into codeword
- points (using >CFA) and deciding what to do with them. What it does depends on the mode
- of the interpreter (in variable STATE). When STATE is zero, the interpreter just calls
- each word as it looks them up. (Known as immediate mode).
+ pointers (using >CFA) and deciding what to do with them.
+
+ What it does depends on the mode of the interpreter (in variable STATE).
+
+ When STATE is zero, the interpreter just runs each word as it looks them up. This is known as
+ immediate mode.
The interesting stuff happens when STATE is non-zero -- compiling mode. In this mode the
- interpreter just appends the codeword pointers to user memory (the HERE variable points to
- the next free byte of user memory).
+ interpreter appends the codeword pointer to user memory (the HERE variable points to the next
+ free byte of user memory).
So you may be able to see how we could define : (COLON). The general plan is:
(1) Use WORD to read the name of the function being defined.
- (2) Construct the dictionary entry header in user memory:
+ (2) Construct the dictionary entry -- just the header part -- in user memory:
- pointer to previous word (from LATEST) +-- Afterwards, HERE points here, where
+ pointer to previous word (from LATEST) +-- Afterwards, HERE points here, where
^ | the interpreter will start appending
| V codewords.
+--|------+---+---+---+---+---+---+---+---+------------+
+---------+---+---+---+---+---+---+---+---+------------+
len pad codeword
- (3) Set LATEST to point to the newly defined word and most importantly leave HERE pointing
- just after the new codeword. This is where the interpreter will append codewords.
+ (3) Set LATEST to point to the newly defined word, ...
+
+ (4) .. and most importantly leave HERE pointing just after the new codeword. This is where
+ the interpreter will append codewords.
- (4) Set STATE to 1. Go into compile mode so the interpreter starts appending codewords.
+ (5) Set STATE to 1. This goes into compile mode so the interpreter starts appending codewords to
+ our partially-formed header.
After : has run, our input is here:
+---------+---+---+---+---+---+---+---+---+------------+------------+------------+
len pad codeword
+ The issue is what happens next. Obviously what we _don't_ want to happen is that we
+ read ";" and compile it and go on compiling everything afterwards.
+
+ At this point, FORTH uses a trick. Remember the length byte in the dictionary definition
+ isn't just a plain length byte, but can also contain flags. One flag is called the
+ IMMEDIATE flag (F_IMMED in this code). If a word in the dictionary is flagged as
+ IMMEDIATE then the interpreter runs it immediately _even if it's in compile mode_.
+
+ I hope I don't need to explain that ; (SEMICOLON) just such a word, flagged as IMMEDIATE.
+ And all it does is append the codeword for EXIT on to the current definition and switch
+ back to immediate mode (set STATE back to 0). Shortly we'll see the actual definition
+ of ; and we'll see that it's really a very simple definition, declared IMMEDIATE.
+
+ After the interpreter reads ; and executes it 'immediately', we get this:
+
+ +---------+---+---+---+---+---+---+---+---+------------+------------+------------+------------+
+ | LINK | 6 | D | O | U | B | L | E | 0 | DOCOL | DUP | + | EXIT |
+ +---------+---+---+---+---+---+---+---+---+------------+------------+------------+------------+
+ len pad codeword ^
+ |
+ HERE
+
+ STATE is set to 0.
+
+ And that's it, job done, our new definition is compiled, and we're back in immediate mode
+ just reading and executing words, perhaps including a call to test our new word DOUBLE.
+ The only last wrinkle in this is that while our word was being compiled, it was in a
+ half-finished state. We certainly wouldn't want DOUBLE to be called somehow during
+ this time. There are several ways to stop this from happening, but in FORTH what we
+ do is flag the word with the HIDDEN flag (F_HIDDEN in this code) just while it is
+ being compiled. This prevents FIND from finding it, and thus in theory stops any
+ chance of it being called.
+ Compared to the description above, the actual definition of : (COLON) is comparatively simple:
*/
defcode ":",1,,COLON
movl $1,var_STATE
NEXT
+/*
+ , (COMMA) is a standard FORTH word which appends a 32 bit integer (normally a codeword
+ pointer) to the user data area pointed to by HERE, and adds 4 to HERE.
+*/
+
defcode ",",1,,COMMA
pop %eax // Code pointer to store.
call _COMMA
movl %edi,var_HERE // Update HERE (incremented)
ret
+/*
+ ; (SEMICOLON) is also elegantly simple. Notice the F_IMMED flag.
+*/
+
defcode ";",1,F_IMMED,SEMICOLON
movl $EXIT,%eax // EXIT is the final codeword in compiled words.
call _COMMA // Store it.
movl %eax,var_STATE
NEXT
+/*
+ EXTENDING THE COMPILER ----------------------------------------------------------------------
+
+ Words flagged with IMMEDIATE (F_IMMED) aren't just for the FORTH compiler to use. You can define
+ your own IMMEDIATE words too, and this is a crucial aspect when extending basic FORTH, because
+ it allows you in effect to extend the compiler itself. Does gcc let you do that?
+
+ Standard FORTH words like IF, WHILE, .", [ and so on are all written as extensions to the basic
+ compiler, and are all IMMEDIATE words.
+
+ The IMMEDIATE word toggles the F_IMMED (IMMEDIATE flag) on the most recently defined word,
+ or on the current word if you call it in the middle of a definition.
+
+ Typical usage is:
+
+ : MYIMMEDWORD IMMEDIATE
+ ...definition...
+ ;
+
+ but some FORTH programmers write this instead:
+
+ : MYIMMEDWORD
+ ...definition...
+ ; IMMEDIATE
+
+ The two usages are equivalent, to a first approximation.
+*/
+
defcode "IMMEDIATE",9,F_IMMED,IMMEDIATE
call _IMMEDIATE
NEXT
xorb $F_IMMED,(%edi) // Toggle the IMMED bit.
ret
+/*
+ HIDDEN toggles the other flag, F_HIDDEN, of the latest word. Note that words flagged
+ as hidden are defined but cannot be called, so this is rarely used.
+*/
+
defcode "HIDDEN",6,,HIDDEN
call _HIDDEN
NEXT
xorb $F_HIDDEN,(%edi) // Toggle the HIDDEN bit.
ret
- defcode "CHAR",4,,CHAR
- call _WORD // Returns %ecx = length, %edi = pointer to word.
- xor %eax,%eax
- movb (%edi),%al // Get the first character of the word.
- push %eax // Push it onto the stack.
- NEXT
+/*
+ ' (TICK) is a standard FORTH word which returns the codeword pointer of the next word.
+
+ The common usage is:
+
+ ' FOO ,
+
+ which appends the codeword of FOO to the current word we are defining (this only works in compiled code).
+
+ You tend to use ' in IMMEDIATE words. For example an alternate (and rather useless) way to define
+ a literal 2 might be:
-/* This definiton of ' (TICK) is strictly cheating - it also only works in compiled code. */
+ : LIT2 IMMEDIATE
+ ' LIT , \ Appends LIT to the currently-being-defined word
+ 2 , \ Appends the number 2 to the currently-being-defined word
+ ;
+
+ So you could do:
+
+ : DOUBLE LIT2 * ;
+
+ (If you don't understand how LIT2 works, then you should review the material about compiling words
+ and immediate mode).
+
+ This definition of ' uses a cheat which I copied from buzzard92. As a result it only works in
+ compiled code. It is possible to write a version of ' based on WORD, FIND, >CFA which works in
+ immediate mode too.
+*/
defcode "'",1,,TICK
lodsl // Get the address of the next word and skip it.
pushl %eax // Push it on the stack.
NEXT
+/*
+ BRANCHING ----------------------------------------------------------------------
+
+ It turns out that all you need in order to define looping constructs, IF-statements, etc.
+ are two primitives.
+
+ BRANCH is an unconditional branch. 0BRANCH is a conditional branch (it only branches if the
+ top of stack is zero).
+
+ The diagra below shows how BRANCH works in some imaginary compiled word. When BRANCH executes,
+ %esi starts by pointing to the offset field (compare to LIT above):
+
+ +---------------------+-------+---- - - ---+------------+------------+---- - - - ----+------------+
+ | (Dictionary header) | DOCOL | | BRANCH | offset | (skipped) | word |
+ +---------------------+-------+---- - - ---+------------+-----|------+---- - - - ----+------------+
+ ^ | ^
+ | | |
+ | +-----------------------+
+ %esi added to offset
+
+ The offset is added to %esi to make the new %esi, and the result is that when NEXT runs, execution
+ continues at the branch target. Negative offsets work as expected.
+
+ 0BRANCH is the same except the branch happens conditionally.
+
+ Now standard FORTH words such as IF, THEN, ELSE, WHILE, REPEAT, etc. can be implemented entirely
+ in FORTH. They are IMMEDIATE words which append various combinations of BRANCH or 0BRANCH
+ into the word currently being compiled.
+
+ As an example, code written like this:
+
+ condition-code IF true-part THEN rest-code
+
+ compiles to:
+
+ condition-code 0BRANCH OFFSET true-part rest-code
+ | ^
+ | |
+ +-------------+
+*/
+
defcode "BRANCH",6,,BRANCH
add (%esi),%esi // add the offset to the instruction pointer
NEXT
lodsl // otherwise we need to skip the offset
NEXT
+/*
+ PRINTING STRINGS ----------------------------------------------------------------------
+
+ LITSTRING and EMITSTRING are primitives used to implement the ." operator (which is
+ written in FORTH). See the definition of that operator below.
+*/
+
defcode "LITSTRING",9,,LITSTRING
lodsl // get the length of the string
push %eax // push it on the stack
push %esi // push the address of the start of the string
addl %eax,%esi // skip past the string
- addl $3,%esi // but round up to next 4 byte boundary
+ addl $3,%esi // but round up to next 4 byte boundary
andl $~3,%esi
NEXT
mov $1,%ebx // 1st param: stdout
pop %ecx // 2nd param: address of string
pop %edx // 3rd param: length of string
-
mov $__NR_write,%eax // write syscall
int $0x80
-
NEXT
+/*
+ COLD START AND INTERPRETER ----------------------------------------------------------------------
+
+ COLD is the first FORTH function called, almost immediately after the FORTH system "boots".
+
+ INTERPRETER is the FORTH interpreter ("toploop", "toplevel" or "REPL" might be a more accurate
+ description -- see: http://en.wikipedia.org/wiki/REPL).
+*/
+
+
// COLD must not return (ie. must not call EXIT).
defword "COLD",4,,COLD
.int INTERPRETER // call the interpreter loop (never returns)
interpret_is_lit:
.int 0 // Flag used to record if reading a literal
+/*
+ ODDS AND ENDS ----------------------------------------------------------------------
+
+ CHAR puts the ASCII code of the first character of the following word on the stack. For example
+ CHAR A puts 65 on the stack.
+
+ SYSEXIT exits the process using Linux exit syscall.
+*/
+
+ defcode "CHAR",4,,CHAR
+ call _WORD // Returns %ecx = length, %edi = pointer to word.
+ xor %eax,%eax
+ movb (%edi),%al // Get the first character of the word.
+ push %eax // Push it onto the stack.
+ NEXT
+
// NB: SYSEXIT must be the last entry in the built-in dictionary.
defcode SYSEXIT,7,,SYSEXIT
pop %ebx
mov $__NR_exit,%eax
int $0x80
-/*----------------------------------------------------------------------
- * Input buffer & initial input.
- */
+/*
+ START OF FORTH CODE ----------------------------------------------------------------------
+
+ We've now reached the stage where the FORTH system is running and self-hosting. All further
+ words can be written as FORTH itself, including words like IF, THEN, .", etc which in most
+ languages would be considered rather fundamental.
+
+ As a kind of trick, I prefill the input buffer with the initial FORTH code. Once this code
+ has run (when we get to the "OK" prompt), this input buffer is reused for reading any further
+ user input.
+
+ Some notes about the code:
+
+ \ (backslash) is the FORTH way to start a comment which goes up to the next newline. However
+ because this is a C-style string, I have to escape the backslash, which is why they appear as
+ \\ comment.
+
+ Similarly, any backslashes in the code are doubled, and " becomes \" (eg. the definition of ."
+ is written as : .\" ... ;)
+
+ I use indenting to show structure. The amount of whitespace has no meaning to FORTH however
+ except that you must use at least one whitespace character between words, and words themselves
+ cannot contain whitespace.
+
+ FORTH is case-sensitive. Use capslock!
+
+ Enjoy!
+*/
+
.data
.align 4096
buffer:
- // XXX gives 'Warning: unterminated string; newline inserted' messages which you can ignore
+ // Multi-line constant gives 'Warning: unterminated string; newline inserted' messages which you can ignore.
.ascii "\
\\ Define some character constants
: '\\n' 10 ;
\\ that the input buffer where the string comes from may be overwritten by the time we
\\ come round to running the function). We store the string in the compiled function
\\ like this:
-\\ LITSTRING, string length, string rounded up to 4 bytes, EMITSTRING, ...
+\\ ..., LITSTRING, string length, string rounded up to 4 bytes, EMITSTRING, ...
: .\" IMMEDIATE
STATE @ \\ compiling?
IF
\\ ALLOT is used to allocate (static) memory when compiling. It increases HERE by
\\ the amount given on the stack.
-: ALLOT HERE +! ;
+\\: ALLOT HERE +! ;
\\ Finally print the welcome prompt.
+.\" JONESFORTH VERSION \" VERSION @ . CR
.\" OK \"
"
.int buffer
bufftop:
.int _initbufftop
+
+/* END OF jonesforth.S */
git.annexia.org / jonesforth.git / blobdiff