Mirror of CollapseOS
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

156 lines
5.8KB

  1. Collapse OS' Forth implementation notes
  2. *** EXECUTION MODEL
  3. After having read a line through readln, we want to interpret it. As a general
  4. rule, we go like this:
  5. 1. read single word from line
  6. 2. Can we find the word in dict?
  7. 3. If yes, execute that word, goto 1
  8. 4. Is it a number?
  9. 5. If yes, push that number to PS, goto 1
  10. 6. Error: undefined word.
  11. *** EXECUTING A WORD
  12. At it's core, executing a word is pushing the wordref on PS and calling EXECUTE.
  13. Then, we let the word do its things. Some words are special, but most of them
  14. are of the compiledWord type, and that's their execution that we describe here.
  15. First of all, at all time during execution, the Interpreter Pointer (IP) points
  16. to the wordref we're executing next.
  17. When we execute a compiledWord, the first thing we do is push IP to the Return
  18. Stack (RS). Therefore, RS' top of stack will contain a wordref to execute next,
  19. after we EXIT.
  20. At the end of every compiledWord is an EXIT. This pops RS, sets IP to it, and
  21. continues.
  22. *** Stack management
  23. The Parameter stack (PS) is maintained by SP and the Return stack (RS) is
  24. maintained by IX. This allows us to generally use push and pop freely because PS
  25. is the most frequently used. However, this causes a problem with routine calls:
  26. because in Forth, the stack isn't balanced within each call, our return offset,
  27. when placed by a CALL, messes everything up. This is one of the reasons why we
  28. need stack management routines below. IX always points to RS' Top Of Stack (TOS)
  29. This return stack contain "Interpreter pointers", that is a pointer to the
  30. address of a word, as seen in a compiled list of words.
  31. *** Dictionary
  32. A dictionary entry has this structure:
  33. - Xb name. Arbitrary long number of character (but can't be bigger than
  34. input buffer, of course). not null-terminated
  35. - 2b prev offset
  36. - 1b size + IMMEDIATE flag
  37. - 2b code pointer
  38. - Parameter field (PF)
  39. The prev offset is the number of bytes between the prev field and the previous
  40. word's code pointer.
  41. The size + flag indicate the size of the name field, with the 7th bit being the
  42. IMMEDIATE flag.
  43. The code pointer point to "word routines". These routines expect to be called
  44. with IY pointing to the PF. They themselves are expected to end by jumping to
  45. the address at (IP). They will usually do so with "jp next".
  46. That's for "regular" words (words that are part of the dict chain). There are
  47. also "special words", for example NUMBER, LIT, FBR, that have a slightly
  48. different structure. They're also a pointer to an executable, but as for the
  49. other fields, the only one they have is the "flags" field.
  50. *** System variables
  51. There are some core variables in the core system that are referred to directly
  52. by their address in memory throughout the code. The place where they live is
  53. configurable by the RAMSTART constant in conf.fs, but their relative offset is
  54. not. In fact, they're mostlly referred to directly as their numerical offset
  55. along with a comment indicating what this offset refers to.
  56. This system is a bit fragile because every time we change those offsets, we
  57. have to be careful to adjust all system variables offsets, but thankfully,
  58. there aren't many system variables. Here's a list of them:
  59. RAMSTART INITIAL_SP
  60. +02 CURRENT
  61. +04 HERE
  62. +06 IP
  63. +08 FLAGS
  64. +0a PARSEPTR
  65. +0c CINPTR
  66. +0e WORDBUF
  67. +2e SYSVNXT
  68. +4e INTJUMP
  69. +51 SYSTEM SCRATCHPAD
  70. +60 RAMEND
  71. INITIAL_SP holds the initial Stack Pointer value so that we know where to reset
  72. it on ABORT
  73. CURRENT points to the last dict entry.
  74. HERE points to current write offset.
  75. IP is the Interpreter Pointer
  76. FLAGS holds global flags. Only used for prompt output control for now.
  77. PARSEPTR holds routine address called on (parse)
  78. CINPTR holds routine address called on C<
  79. WORDBUF is the buffer used by WORD
  80. SYSVNXT is the buffer+tracker used by (sysv)
  81. INTJUMP All RST offsets (well, not *all* at this moment, I still have to free
  82. those slots...) in boot binaries are made to jump to this address. If you use
  83. one of those slots for an interrupt, write a jump to the appropriate offset in
  84. that RAM location.
  85. SYSTEM SCRATCHPAD is reserved for temporary system storage or can be reserved
  86. by low-level drivers. These are the current usages of this space throughout the
  87. project:
  88. * 0x51-0x53: (c<) pointer during in-memory initialization (see below)
  89. * 0x53-0x5b: ACIA buffer pointers in RC2014 recipes.
  90. *** Initialization sequence
  91. On boot, we jump to the "main" routine in boot.fs which does very few things.
  92. It sets up the SP register, CURRENT and HERE to LATEST (saved in stable ABI),
  93. then look for the BOOT word and calls it.
  94. In a normal system, BOOT is in icore and does a few things:
  95. 1. Find "(parse)" and set "(parse*)" to it.
  96. 2. Find "(c<)" a set CINPTR to it (what C< calls).
  97. 3. Write LATEST in SYSTEM SCRATCHPAD ( see below )
  98. 4. Find "INIT". If found, execute. Otherwise, execute "INTERPRET"
  99. On a bare system (only boot+icore), this sequence will result in "(parse)"
  100. reading only decimals and (c<) reading characters from memory starting from
  101. CURRENT (this is why we put CURRENT in SYSTEM SCRATCHPAD, it tracks current
  102. pos ).
  103. This means that you can put initialization code in source form right into your
  104. binary, right after your last compiled dict entry and it's going to be executed
  105. as such until you set a new (c<).
  106. Note that there is no EMIT in a bare system. You have to take care of supplying
  107. one before your load core.fs and its higher levels.
  108. Also note that this initialization code is fighting for space with HERE: New
  109. entries to the dict will overwrite that code! Also, because we're barebone, we
  110. can't have comments. This leads to peculiar code in this area. If you see weird
  111. whitespace usage, it's probably because not using those whitespace would result
  112. in dict entry creation overwriting the code before it has the chance to be
  113. interpreted.