GitHub - cesarblum/sectorforth: sectorforth is a 16-bit x86 Forth that fits in a 512-byte boot sector.

sectorforth is a 16-bit x86 Forth that fits in a 512-byte boot sector. Inspiration to write sectorforth came from a 1996 Usenet thread (in particular, Bernd Paysan's first post on the thread). Batteries not included sectorforth contains only the eight primitives outlined in the Usenet post above, five variables for manipulating internal state, and two I/O primitives. With that minimal set of building blocks, words for branching, compiling, manipulating the return stack, etc. can all be written in Forth itself (check out the examples!). The colon compiler (:) is available, so new words can be defined easily (that means ; is also there, of course). Contrary to many Forth implementations, sectorforth does not attempt to convert unknown words to numbers, since numbers can be produced using the available primitives. The two included I/O primitives are sufficient to write a more powerful interpreter that can parse numbers. Primitives Primitive Stack effects Description @ ( addr -- x ) Fetch memory contents at addr ! ( x addr -- ) Store x at addr sp@ ( -- sp ) Get pointer to top of data stack rp@ ( -- rp ) Get pointer to top of return stack 0= ( x -- flag ) -1 if top of stack is 0, 0 otherwise + ( x y -- z ) Sum the two numbers at the top of the stack nand ( x y -- z ) NAND the two numbers at the top of the stack exit ( r:addr -- ) Pop return stack and resume execution at addr key ( -- x ) Read key stroke as ASCII character emit ( x -- ) Print low byte of x as an ASCII character Variables Variable Description state 0: execute words; 1: compile word addresses to the dictionary tib Terminal input buffer, where input is parsed from >in Current parsing offset into terminal input buffer here Pointer to next free position in the dictionary latest Pointer to most recent dictionary entry Compiling sectorforth was developed using NASM 2.15.01. Earlier versions of NASM are probably capable of compiling it, but that hasn't been tested. To compile sectorforth, just run make: $ make That will produce a compiled binary (sectorforth.bin) and a floppy disk image (sectorforth.img) containing the binary in its boot sector. Running The makefile contains two targets for running sectorforth in QEMU: debug starts QEMU in debug mode, with execution paused. That allows you to set up a remote target in GDB (target remote localhost:1234) and set any breakpoints you want before sectorforth starts running. run simply runs sectorforth in QEMU. Usage Up to 4KB of input can be entered per line. After pressing return, the interpreter parses one word at a time an interprets it (i.e. executes it or compiles it, according to the current value of the state variable). sectorforth does not print the ok prompt familiar to Forth users. However, if a word is not found in the dictionary, the error message !! is printed in red, letting you know an error happened. When a word is not found in the dictionary, the interpreter's state is reset: the data and return stacks, as well as the terminal input buffer are cleared, and the interpreter is placed in interpretation mode. Other errors (e.g. compiling an invalid address in a word definition and attempting to execute it) are not handled gracefully, and will crash the interpreter. Code structure Comments throughout the code assume familiarity with Forth and how it is commonly implemented. If you're not familiar with Forth, read Leo Brodie's Starting Forth. If you're not familiar with how Forth is implemented on x86, read the assembly code for Richard W.M. Jones' jonesforth. sectorforth draws a lot of inspiration from jonesforth, but the latter does a much better job at explaining the basics in its comments. For an excellent introduction to threaded code techniques, and to how to implement Forth in different architectures, read Brad Rodriguez's Moving Forth.