mirror of
https://github.com/hsoft/collapseos.git
synced 2024-12-26 04:28:05 +11:00
68a7be3707
Doing this was a bit stupid. These offsets are constants. Moreover, having them in stable ABI had us construct the boot binary from the stable ABI of the host, making it very difficult to change RAMSTART for a new system.
110 lines
3.7 KiB
Plaintext
110 lines
3.7 KiB
Plaintext
Collapse OS' Forth implementation notes
|
|
|
|
*** EXECUTION MODEL
|
|
|
|
After having read a line through readln, we want to interpret it. As a general
|
|
rule, we go like this:
|
|
|
|
1. read single word from line
|
|
2. Can we find the word in dict?
|
|
3. If yes, execute that word, goto 1
|
|
4. Is it a number?
|
|
5. If yes, push that number to PS, goto 1
|
|
6. Error: undefined word.
|
|
|
|
*** EXECUTING A WORD
|
|
|
|
At it's core, executing a word is pushing the wordref on PS and calling EXECUTE.
|
|
Then, we let the word do its things. Some words are special, but most of them
|
|
are of the compiledWord type, and that's their execution that we describe here.
|
|
|
|
First of all, at all time during execution, the Interpreter Pointer (IP) points
|
|
to the wordref we're executing next.
|
|
|
|
When we execute a compiledWord, the first thing we do is push IP to the Return
|
|
Stack (RS). Therefore, RS' top of stack will contain a wordref to execute next,
|
|
after we EXIT.
|
|
|
|
At the end of every compiledWord is an EXIT. This pops RS, sets IP to it, and
|
|
continues.
|
|
|
|
*** Stack management
|
|
|
|
The Parameter stack (PS) is maintained by SP and the Return stack (RS) is
|
|
maintained by IX. This allows us to generally use push and pop freely because PS
|
|
is the most frequently used. However, this causes a problem with routine calls:
|
|
because in Forth, the stack isn't balanced within each call, our return offset,
|
|
when placed by a CALL, messes everything up. This is one of the reasons why we
|
|
need stack management routines below. IX always points to RS' Top Of Stack (TOS)
|
|
|
|
This return stack contain "Interpreter pointers", that is a pointer to the
|
|
address of a word, as seen in a compiled list of words.
|
|
|
|
*** Dictionary
|
|
|
|
A dictionary entry has this structure:
|
|
|
|
- Xb name. Arbitrary long number of character (but can't be bigger than
|
|
input buffer, of course). not null-terminated
|
|
- 2b prev offset
|
|
- 1b size + IMMEDIATE flag
|
|
- 2b code pointer
|
|
- Parameter field (PF)
|
|
|
|
The prev offset is the number of bytes between the prev field and the previous
|
|
word's code pointer.
|
|
|
|
The size + flag indicate the size of the name field, with the 7th bit being the
|
|
IMMEDIATE flag.
|
|
|
|
The code pointer point to "word routines". These routines expect to be called
|
|
with IY pointing to the PF. They themselves are expected to end by jumping to
|
|
the address at (IP). They will usually do so with "jp next".
|
|
|
|
That's for "regular" words (words that are part of the dict chain). There are
|
|
also "special words", for example NUMBER, LIT, FBR, that have a slightly
|
|
different structure. They're also a pointer to an executable, but as for the
|
|
other fields, the only one they have is the "flags" field.
|
|
|
|
*** System variables
|
|
|
|
There are some core variables in the core system that are referred to directly
|
|
by their address in memory throughout the code. The place where they live is
|
|
configurable by the RAMSTART constant in conf.fs, but their relative offset is
|
|
not. In fact, they're mostlly referred to directly as their numerical offset
|
|
along with a comment indicating what this offset refers to.
|
|
|
|
This system is a bit fragile because every time we change those offsets, we
|
|
have to be careful to adjust all system variables offsets, but thankfully,
|
|
there aren't many system variables. Here's a list of them:
|
|
|
|
RAMSTART INITIAL_SP
|
|
+02 CURRENT
|
|
+04 HERE
|
|
+06 IP
|
|
+08 FLAGS
|
|
+0a PARSEPTR
|
|
+0c CINPTR
|
|
+0e WORDBUF
|
|
+2e SYSVNXT
|
|
+4e RAMEND
|
|
|
|
INITIAL_SP holds the initial Stack Pointer value so that we know where to reset
|
|
it on ABORT
|
|
|
|
CURRENT points to the last dict entry.
|
|
|
|
HERE points to current write offset.
|
|
|
|
IP is the Interpreter Pointer
|
|
|
|
FLAGS holds global flags. Only used for prompt output control for now.
|
|
|
|
PARSEPTR holds routine address called on (parse)
|
|
|
|
CINPTR holds routine address called on C<
|
|
|
|
WORDBUF is the buffer used by WORD
|
|
|
|
SYSVNXT is the buffer+tracker used by (sysv)
|