antforth v3.3.0

Full Changelog: v3.2.1...v3.3.0

antforth v3.3.0

Twelve new words, stack-underflow checks on every word that takes arguments,
and fixes for banked memory. Tested on real MicroBeast hardware.

New words

Stack

• NIP ( a b -- b ), TUCK ( a b -- b a b ) (Core Extensions)
• -ROT ( a b c -- c a b ), the reverse of ROT (antforth extension)
• ? ( addr -- ) prints the value stored at an address, the same as @ . (Tools)

Comparisons

• <>, 0<>, 0>, U> (Core Extensions)
• <=, >=, signed (antforth extensions)

Loops

• BEGIN … AGAIN for loops that never end on their own, such as task bodies
  and event loops. Leave with EXIT.
• ?DO runs zero times when the limit equals the start (DO would run 65,536
  times). It works with LOOP, +LOOP, LEAVE, UNLOOP, I and J.

Core Extensions coverage goes from 15 to 23 of the 46 words.

Stack underflow is caught everywhere

Every kernel word and assembler mnemonic that takes stack arguments now raises
-4 stack underflow when they're missing. The check runs before the word
changes anything. Before, DUP, 0=, 1+, TYPE, FILL, MOVE,
ACTIVATE and about 45 others silently worked on whatever was left in a
register.

• PICK and ROLL check that the stack holds u items.
• SET-ORDER and RESTORE-INPUT count their arguments correctly.
• An assembler instruction missing an operand raises -4 before it writes any
  code bytes, so a caught error leaves HERE where it was.

Fixes

• >NUMBER swapped the two halves of its starting value. With a nonzero
  start, 1 0 S" 0" >NUMBER 2DROP D. printed 655360 instead of 10.
  Starting from 0 0, as most code does, wasn't affected.
• Banked words could hide or hang kernel words. Giving +BANK the same
  physical page twice made two banks share one piece of RAM, so defining words
  in one bank overwrote dictionary entries in the other. A lookup could then
  miss CR or BANK!, or hang. +BANK now refuses a page that is already
  listed (dup?, error -2), and so does the boot page list.
• Parsing near the top of a bank could write into fixed RAM. When a bank
  above 0 was nearly full, the parse buffer and PAD ran past $C000 and
  overwrote bank 0's dictionary. Banks above 0 now end at $BF58, so .BANKS
  shows 16,216 bytes free per bank instead of 16,384.
• WORD refuses words over 128 characters with error -18, so even
  EVALUATE can't overflow the parse buffer.

Things to know when upgrading

• Room for only two tasks. Every task's control block (TCB) must sit below
  $8000, and this kernel leaves room for two named tasks
  (TASK CONSTANT name), with 25 bytes to spare. A third TASK raises -8.
  Create your tasks before anything else. TRAFFIC.FTH now does this, so
  LIGHTS is task 1. To see the free room, type DECIMAL 32768 HERE - . at a
  fresh prompt. See "How many tasks fit" in docs/phase6-multitasker.md.
• Scripts that add the same page twice ($22 +BANK $22 +BANK) now fail.
  Use a different page for each bank.
• The underflow checks cost some speed: INCLUDE is about 10–14% slower in
  CPU cycles. Disk I/O is unchanged, so the real-world difference is smaller.
• Banked code must leave 168 bytes below $C000. Code that filled a bank to
  the brim before now raises -8 sooner.

Size

antforth.com is 31,395 bytes, 641 more than v3.2.1.