StahlOS Forth Internals

Some internal details of the Forth implementation used in the StahlOS kernel is briefly described here. This ABI is tentative and may change.

Word Structure

StahlOS Forth is a DTC Forth.

Words must be aligned to a multiple of 8 bytes.

0x00 +-------------------+ --\
     |   Previous Word   |   |
     |   Header Address  |   |
0x08 +-------------------+   |
     |    Name Length    |   |
0x09 +-------------------+   |
     |     Word Flags    |   |
     |    (see below)    |   |
0x0c +-------------------+   |
     |     Word Name     |   +-- Word Header
     +-------------------+   |
     |      Padding      |   |  /- Multiple of 4 bytes
     |   (0 to 3 bytes)  |   |  |
0x?? +-------------------+ - | -+
     |    Name Length    |   |  |
0x?? +-------------------+   |  |
     | Padding (3 bytes) |   |  |
0x?? +-------------------+ --/--/
     |     Code Field    |   \
     +-------------------+   +-- Word Body
     |  Parameter Field  |   |
     +-------------------+ --/

Word Flags are:

       0x08            0x09            0x0a            0x0b
 LSB         MSB LSB         MSB LSB         MSB LSB         MSB
+---------------+-+-+-+-+-+-+-+-+---------------+---------------+
|  Name Length  |S|I|0|0|0|0|0|0|    Reserved   |    Reserved   |
+---------------+-+-+-+-+-+-+-+-+---------------+---------------+
  • 0: Reserved, must be zero.
  • S: Smudge. 0 for visible, 1 for hidden.
  • I: Immediate. 0 for non-immediate, 1 for immediate.

Registers

  • x0-x15: Temporaries
  • x16-x19: Reserved for processes
  • x20: The Forth instruction pointer
  • x21: The process context pointer
  • x22: The stack base pointer
  • x23: The stack top pointer
  • x24: The top stack item
  • x25: The return stack base pointer
  • x26: The return stack top pointer
  • x27: The top return stack item
  • x28: Temporary
  • x29: Temporary, used by DOES> / (DODOES)

The x22 register should always be x21 + 0x0200. The x23 register should be x22 + n, where n is the depth of the stack in bytes.

x25 and x26 have the same relationship x22 and x23 do but for the return stack, with x25 always containing x21 + 0x0100.

Process Context

0x0000 +---------------------------+---------------------------+
       |    Low 64 Bits of PID     |  Saved Forth Insn Pointer |
0x0010 +---------------------------+---------------------------+
       |       Dict Pointer        |    Dict Remaining Length  |
0x0020 +---------------------------+---------------------------+
       |    Last Defined Header    |       Process Flags       |
0x0030 +---------------------------+---------------------------+
       |       Source Address      |       Source Length       |
0x0040 +---------------------------+---------------------------+
       |                                                       |
      ...                       Reserved                      ...
       |                                                       |
0x00e0 +---------------------------+---------------------------+
       |         Saved x16         |         Saved x17         |
0x00f0 +---------------------------+---------------------------+
       |         Saved x18         |         Saved x19         |
0x0100 +---------------------------+---------------------------+
       | Saved Return Stack Depth  |                           |
0x0108 +---------------------------+                           |
       |                                                       |
      ...                     Return Stack                    ...
       |                                                       |
0x0200 +---------------------------+---------------------------+
       |     Saved Stack Depth     |                           |
0x0208 +---------------------------+                           |
       |                                                       |
      ...                        Stack                        ...
       |                                                       |
0x0400 +-------------------------------------------------------+

Process Flags are:

       0x28            0x29            0x2a            0x2b
 LSB         MSB LSB         MSB LSB         MSB LSB         MSB
+-+-+-----------+---------------+---------------+---------------+
|B|S| Reserved  |    Reserved   |    Reserved   |    Reserved   |
+-+-+-----------+---------------+---------------+---------------+

       0x2c            0x2d            0x2e            0x2f
 LSB         MSB LSB         MSB LSB         MSB LSB         MSB
+---------------+---------------+---------------+---------------+
|    Reserved   |    Reserved   |    Reserved   |    Reserved   |
+---------------+---------------+---------------+---------------+
  • B: Base. 0 for decimal, 1 for hex.
  • S: State. 0 for interpret, 1 for compile.