/* 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.16 2007-09-08 17:02:11 rich Exp $
gcc -m32 -nostdlib -static -Wl,-Ttext,0 -o jonesforth jonesforth.S
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
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
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).
+
+ This is how BRANCH works. When BRANCH executes, %esi starts by pointing to the offset:
+
+ +---------------------+-------+---- - - ---+------------+------------+---- - - - ----+------------+
+ | (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. are 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
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).
+*/
+
+
// 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 pops the status off the stack and exits the process (using Linux exit syscall).
+*/
+
defcode "CHAR",4,,CHAR
call _WORD // Returns %ecx = length, %edi = pointer to word.
xor %eax,%eax
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 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 ;
.int buffer
bufftop:
.int _initbufftop
+
+/* END OF jonesforth.S */
projects / rrq / jonesforth.git / blobdiff