c3 - A stack-based VM written in C.

What is c3?

• c3 is a stack-based, byte-coded VM.
• c3's opcodes implement many of the standard Forth operations.
• c3 supports IEEE 754 double-precision (64-bit) floating point numbers.
• c3 provides 10 "virtual registers", r0 thru r9.
  • Each register has 6 operations: rX, sX, iX, dX, rX+, and rX-.
• c3 provides 10 temporary words, T0 thru T9.
  • T0-T5 are "normal" words, T6-T8 are INLINE, and T9 is IMMEDIATE.

Goals

The goals for c3 are:

• To have an implementation that is minimal and "intuitively obvious upon casual inspection".
• To be very easy to extend as desired.
• To provide as much flexibility to the programmer as possible.
• To be able to run on Windows, Linux, Apple, and development boards via the Arduino IDE.

Notes about c3:

• c3 is NOT an ANSI-standard Forth system.
• Strings in c3 are null-terminated, not counted.
• The user can add counted strings if desired.
• There are 2 separate memory areas: CODE and VARIABLE.
• The dictionary starts at the end of the CODE area and grows down.
• The dictionary search is not case-sensitive.

Registers

c3 exposes 10 "virtual registers", r0 thru r9. There are 8 register operations: +regs, rX, rX+, rX-, sX, iX, dX, -regs. The names of the register words are case-sensitive: (r0-r9, not R0-R9).

Note: The support for registers is built into c3, so they do NOT show up in "WORDS".

• +regs allocate 10 new registers.
• r4 push register 4 to the stack.
• r4+ push register 4 to the stack, then increment it.
• r4- push register 4 to the stack, then decrement it.
• s4 set register 4 from TOS.
• i4 increment register 4.
• d4 decrement register 4.
• -regs restore the registers to their previous values.

Some example uses of registers:

   : btw  ( n l h--f )  +regs  s3 s2 s1  r2 r1 <   r1 r3 <  and  -regs ;
   : btwi ( n l h--f )  +regs  s3 s2 s1  r2 r1 <=  r1 r3 <= and  -regs ;
   : 2swap ( a b c d--c d a b )  +regs  s4 s3 s2 s1  r3 r4 r1 r2  -regs ;
   : move ( f t n-- ) +regs  s3 s2 s1  r3 0 do  r1+ c@ r2+ c!  loop  -regs ;
   : fill ( a c n-- ) +regs  s3 s2 s1  r3 0 do  r2 r1+ c!      loop  -regs ;

Temporary words

c3 provides 10 temporary words, T0 thru T9.

• Defining a temporary word does not add an entry to the dictionary.
• Temporary words are intended to be helpful in factoring code.
• A temporary word can be redefined as often as desired.
• When redefined, code references to the previous definition are unchanged.
• T0-T5 are "normal" words, T6-T8 are INLINE, and T9 is IMMEDIATE.
• The names of the temporary words are case-sensitive (T0-T9, not t0-t9).

An example usage of temporary words:

\ The Babylon square root algorithm
: T0 ( n--sqrt ) dup 4 / begin >r dup r@ / r@ + 2 / dup r> - 0= until nip ;
: sqrt ( n--0|sqrt ) dup 0 > if T0 else drop 0 then ;

Inline words

In c3, an "INLINE" word is like a macro ... when compiling INLINE words, c3 copies the contents of the word (up to, but not including the first EXIT) to the target, as opposed to compiling a CALL to the word. This improves performance and often saves space as well. This is especially true on a 64-bit system, where the CELL size is 8. Note that if a word might have an embedded 3 (EXIT) in its implementation (like an address for example), then it should not be marked as INLINE.

Notes on output formatting in ZTYPE and '."':

• %b: output TOS as a binary number
• %c: output TOS as a character
• %d: output TOS as an integer (base 10)
• %e: output an ESCAPE (27)
• %f: output FTOS as a floating point number
• %g: output FTOS as a scientific number
• %i: output TOS as an integer (current base)
• %n: output a CR/LF (13,10)
• %q: output the quote (") character
• %s: output TOS as a string (null terminated, no count byte)
• %t: output a TAB (9)
• %x: output TOS as a hex number

For example: : ascii 127 32 DO I I I I ." %n%d: (%c) %x %b" LOOP ;

Bootstrapping c3

To bootstrap itself, c3 has a simple "machine language parser" that can create words in c3's "machine language". The keyword for that is "-ML-". For example, the c3 opcode for "return from subroutine" is 3, and "duplicate the top of the stack" is 12. So in the beginning of sys-load.h, I define aliases for the opcodes.

• The first four words defined in c3 are:
  • 'INLINE' - mark the last word as inline
  • 'IMMEDIATE' - mark the last word as immediate
  • ':' - define a new c3 word
  • ';' - end word definition

  -ML- INLINE 47 0 3 -MLX-
  -ML- INLINE 47 1 3 -MLX-
  -ML- INLINE 47 6 3 -MLX-
  -ML- INLINE 47 7 3 -MLX-

c3 also defines some 'system-info' words (the addresses of system variables and sizes of buffers).

Everything in c3 is defined from those. See file 'sys-load.h' for details.

Note that this approach gives the user the maximum flexibility. Opcode 12 does not have to be called "DUP", it could just as easily be "(N--NN)" (or "foo--foo/foo", or whatever). But DUP is clear and concise, so that its default name. :)

The dictionary

NOTE: c3 does NOT do a case-sensitive dictionary search.

• A dictionary entry looks like this:
  • xt: cell_t (either 32-bit or 64-bit)
  • flags: byte (IMMEDIATE=$01, INLINE=$02)
  • len: byte
  • name: char[NAME_LEN+1] (NULL terminated)

Default sizes for PC-based systems

• The default NAME_LEN is 13.
• The default CODE_SZ is 128K bytes (code and dictionary).
• The default VARS_SZ is 4MB bytes (strings and variables).
• The default STK_SZ is 64 CELLS (data and return stacks).
• The default LSTK_SZ is 30 CELLS (loop stack, multiple of 3).
• The default REGS_SZ is 100 CELLS (register stack, multiple of 10).
• These are defined in the sys-init.h file.

Building c3:

• Windows: there is a c3.sln file for Visual Studio
  • You can use the either configuration (x86 or x64)
• Linux: there is a makefile
  • "make c3" builds the 64-bit version, c3
  • "make c3-32" builds the 32-bit version, c3-32
  • "make" builds both versions
• Apple: I do not have an Apple, so I cannot build for Apples
  • But c3 is minimal enough that it should be easy to port to an Apple system
• Arduino: there is a c3.ino file
  • I use the Arduino IDE v2.0
  • Edit the section where isBOARD is defined to set the configuration for the board
  • For the RPI Pico and Teensy 4.0, I use:
    • CODE_SZ: 64K
    • VARS_SZ: 96K
    • STK_SZ: 32
    • LSTK_SZ: 30
    • REGS_SZ; 100
    • NAME_LEN: 13

c3 Opcode / Word reference

NOTE: See the sys-load.h file for the implementation of the words defined in the base c3 system.

System opcodes are 2-bytes, starting with 47

String opcodes are 2-bytes, starting with 48

Floating point opcodes are 2-bytes, starting with 49

Opcodes for PCs (Windows and Linux)

Opcodes for Development Boards

Built-in c3 system-information words

Other built-in c3 words

c3 startup behavior

When c3 starts:

• For every parameter on the command line:
  • IF c3 can open the argv[N] as a file, queue it up to be loaded.
  • IF argv[N] can be converted to a number, set rN to that number
  • • ELSE, set rN to argv[N] (e.g. - rN QTYPE will output the parameter)

Example:

Running this: c3 $100 test.txt
will set r1 to #256 and r2 to the address where "test.txt" starts.

Adding new opcodes to c3

If for some reason, there is a need/desire to add more opcodes to c3, this section describes how it can be accomplished.

For example, there might be some functionality in a library you want to make available, or maybe there is a bottleneck in performance you want to improve.

Here is the process:

• For a global opcode:

  • In c3.c, add the new opcode(s) to the appropriate enum.
  • In c3.c, add a NCASE to run() to for each new opcode.
  • In sys-load.h, add a "-ML-" line to LoadStartupWords() for each new opcode.
  • Update your README.md.

• For a target-specific opcode:

  • All work is done in the target's *.h file (e.g. - sys-pc.h).
  • Add the new opcodes(s) to the enum.
  • Target-specific opcodes should have values above 100.
  • Edit LoadStartupWords() and add a "-ML-" line for each new opcode.
  • For example: to define opcode 120 as "NEWOP" ... ParseLine("-ML- NEWOP 120 3 -MLX- INLINE");
  • In doUser(), add cases for the new opcode(s).
  • Update your README.md.