Cornerstone Bytecode Notes

Warning: These notes are incomplete, and there's a fair amount about the Cornerstone bytecode I haven't fathomed.

Cornerstone is written in interpreted bytecode; on the PC, the interpreter is called MME.EXE. The bytecode is for a stack-based VM, with a 16-bit word.

A bytecode program is stored in two files: a .MME file and a .OBJ file. The .MME file is passed to the interpreter; the .OBJ filename is deduced from it (it's assumed to have the same name, substituting ".obj" for ".mme"). The actual bytecode is in the .OBJ file.

MME File Format

The .MME file has a 96-byte header, of which the following fields appear to be the only ones used by the interpreter. All are little-endian words:

Immediately following the header is a table of module offsets. Again, all entries are little-endian words:

For all modules except the last, the end address of a module is the start address of the next module - 1. When the module index is read in, the header word 0x0E is used to work out the end address of the last module; this is appended to the table in memory.

The module index is followed by a 'globals' index:

And this, in turn, is followed by the initial values of these variables.

    DW  g0,g1,...   ; Initial values of program-wide globals.
    DW  m0g0,m0g1,...   ; Initial values of module 1 globals.
    DW  m1g0,m1g1,...   ; Initial values of module 2 globals.
    etc.

Program-wide globals are accessed with the LOADG, PUTG, STOREG, INCG and DECG instructions. PC Cornerstone supports at most 256 globals.

Module globals are accessed with LOADMG, PUTMG etc. PC Cornerstone supports at most 192 module globals. If these instructions are used with a number higher than 192, they refer to interpreter system variables such as the current date or time.

After the globals table, the loader then seeks to the module headers using header word 0x1A. The original VM does not allow the module headers to occupy more than 2k.

Each module header starts with a word; this is the number of words that follow. The subsequent words are procedure addresses relative to the start of the module.

The module headers are followed by the initial contents of VM RAM (aligned to a 256-byte boundary). The interpreter finds offset of initial RAM by: 256 * (header word 0x1A + 1 + ((header word 0x1E * 2) / 256)). This suggests to me that if the module headers happened to be an exact multiple of 256 bytes in size, the interpreter would require 256 empty bytes before the RAM contents.

VM memory layout

To a first approximation, the virtual machine has 128k of RAM — if you were writing a Cornerstone interpreter on anything other than an extremely constrained machine, you'd just allocate 128k and have done with it.

In a situation where the RAM is constrained, it is composed of two segments of the same size, referred to here as 'low' and 'high'. The 'low' segment starts at 0x00000, and the high segment at 0x10000. For example, if only 96k was available for VM RAM, it would appear to the virtual machine as two 48k segments: 0x00000-0x0BFFF and 0x10000-0x1BFFF. Thus, RAM is only contiguous in a full-128k configuration.

Within the VM bytecode an address in RAM is represented by a 16-bit value:

• The top bit selects which half of RAM to use (set for high, clear for low).
• The bottom 15 bits should be doubled to give the address (ie, it can only address even-numbered bytes).
• 0x8001 represents FALSE (a null pointer).

Frequently, the 16-bit VM address is treated as a pointer to a "Tuple" or a "Vector/Tuple" structure. In this case, I refer to it as a "tuple ID" or "vector ID".

Low RAM is initialised from the .MME file; the header word at 0x16 gives the number of words in the initial image. Assuming that X is the first address after the initial image, the memory at X is initialised as:

Word at X:   0000h
Word at X+2: X + 6
Word at X+6: X + 6
Word at X+8: End of interpreter RAM low segment - (X+8)

For example, if the word at 0x16 is 0x4A48, X will be 2 * 0x4A48 = 0x9490, and memory will be initialised as follows:

0x9490: 0000
0x9492: 9496
0x9496: 9496
0x9498: 6B68

VM RAM is split between data and stack memory. The initial split appears to be the top 1/64th of high memory is given to the stack (so 1k on a full 128k system, 512 bytes on a 64k system, etc.). To avoid confusion with the interpreter's own stack (where local variables live) I'm going to call these areas of memory 'vector data' and 'tuple stack' respectively.

'Vector data' memory starts just after the RAM image loaded from file, and has an allocator system I haven't worked out yet. Presumably the four words initialised above represent an empty arena. Since the arena is visible to the bytecode, all interpreters should use the same allocation system, whatever that is.

Strings in RAM are stored in Pascal format:

    WORD length
    BYTE text[];

File I/O

Cornerstone allows up to 25 open files (or 'channels', as it calls them). One of these will be the .OBJ file; its handle is held in the bottom 5 bits of system variable 0xDB.

Channels can either be disk files, or devices such as a printer. In the PC Cornerstone interpreter, files are allocated channel handles 0-23 and the printer gets handle 24.

One file used internally by Cornerstone is called sysbuf.hld. This is created by the interpreter on startup and appears to be a swapfile of some kind.

OBJ File Format

A .OBJ file is a sequence of modules, each aligned to 256 bytes. Modules are a sequence of procedures.

Code is divided into 256-byte blocks. An instruction cannot be split across two different blocks. The blocks are swapped in and out of memory by the interpreter as required. The last instruction encountered in each block must be NEXTB, to instruct the interpreter to load the next block. NEXTB might be at offset 255, or it might come sooner. For example, assembling the sequence:

    PUSH_L3
    OPEN    8

If the PUSH_L3 happened to end up at offset 253, then there would be no room for the OPEN (a 3-byte opcode) at offset 254. So NEXTB would be inserted at offset 254, and the OPEN would be at offset 0 in the next block.

Each procedure starts with a single byte:

Bits 0-6

give the number of local variables used by this procedure. These are initialised to 0x8001 (FALSE).

Bit 7

is set if initial values for local variables follow.

If bit 7 of the intro byte is set, the procedure header is followed by a list of encoded initial values for local variables. Each entry is 2 or 3 bytes, the first one of which is:

Bits 0-5

Index number of local variable, 0-31

Bit 6

If this bit is 0, the two following bytes are the word value to assign. If it is 1, the one following byte is the value; sign-extend it to a word.

Bit 7

Set if this is the last initial value.

Opcodes

Explanation of the "args" column:

"1-> "

pops one word from the stack, pushes none.

"2->1"

pops two words, pushes one.

" ->1"

pops no words, pushes one.

Let $1 refer to the top word on the stack, $2 the one below it, and so forth.
$B is a byte following the instruction byte.
$W is a little-endian word following the instruction byte.

Mnemonics are my own invention.

shift = -$1;
if ($2 == 0x8000) { $2 = 0x4000; --shift; }
$2 = - ((-$2) >> shift);
       

Bits 15-12 are a shift. The word read will be shifted right by
      this amount of bits before being masked.
Bits 11- 8 give the number of bits to read, 0-15.
Bits  7- 4 are the number of a local variable which contains a vector ID.
Bits  3- 0 are the number of the word in the vector.

Bits 15-12 are a shift. The word read will be shifted right by this amount 
      of bits before being masked.
Bits 11- 8 give the number of bits to read, 0-15.
Bits  7- 0 are the number of the word in the vector.

Bits 15-12 are a shift. The word written will be shifted left by this amount 
      of bits before being masked.
Bits 11- 8 give the number of bits to use, 0-15.
Bits  7- 4 are the number of a local variable which contains a vector ID.
Bits  3- 0 are the number of the word in the vector.

Bits 15-12 are a shift. The word written will be shifted left by this amount 
       of bits before being masked.
Bits 11- 8 give the number of bits to use, 0-15.
Bits  7- 0 are the number of the word in the vector.

Bits 15-12 are the bit number, 0-15.
Bit      8 is the value to write. 
Bits  7- 4 are the number of a local variable which contains a vector ID.
Bits  3- 0 are the number of the word in the vector.

Bits 15-12 = bit number
Bit      8 is the value to write. 
Bits  7- 0 are the number of the word in the vector.

0: Cursor right
1: Cursor left
2: Cursor down
3: Cursor up 
4: If cursor column < 80, print a space
5: Clear from cursor row to bottom

0: Scroll area from cursor row to row specified in system variable 0xC4 
  down by $1 lines. Clears area if $1 = 0.
1: Scroll area from cursor row to system variable 0xC4 up by $1 lines. 
  Clears area if $1 = 0.
2: No effect on PC Cornerstone.
3: No effect on PC Cornerstone.
4: Scroll area between rows specified in system variables 0xC4 and 0xC5 down 
   by $1 lines. Clears area if $1 = 0.
5: Scroll area between rows specified in system variables 0xC4 and 0xC5 up
   by $1 lines. Clears area if $1 = 0.
6: Draw a horizontal line to column $1.

$1 = length of first string
$2 = offset within first vector
$3 = length of second string
$4 = vector address of first string
$5 = vector address of second string

Bits 0-3 of the opcode give the number of a local variable which holds the 
         vector ID.
Bits 4-5 of the opcode give the number of the word to read from the vector.

System variables

When module globals are accessed, a variable number of 0xC0 or higher indicates an interpreter system variable:

0xC0:   Controls behaviour of keyboard input -- how, I'm not sure.
0xC1:   Set to FALSE to disable screen output
0xC2:   Not used by PC Cornerstone
0xC3:   Not used by PC Cornerstone
0xC4:   Used to define window(s) on the screen.
0xC5:   Used to define window(s) on the screen.
0xC6:   Extended error code? Set to 7 if READREC fails.
0xC7:   Screen width, columns - 1
0xC8:   Screen height, rows - 1
0xC9:   Cursor column
0xCA:   Cursor row
0xCC:   Record size for READREC / WRITEREC
0xCD:   Current month
0xCE:   Current day 
0xCF:   Current year
0xD0:   Current time, hours
0xD1:   Current time, minutes 
0xD2:   Current time, seconds
0xD3:   Used by opcode 0x5F 0x22.
0xD4:   Control-Break flag (0 if Control-Break has been pressed.)
0xD5:   Screen attributes:
        Bit 0: Reverse video
        Bit 3: Bright
        Bit 5: Blinking 
0xD7:   A 3-letter string, encoded into 16 bits as:
        enc(str[0]) << 11 | enc(str[1]) * 45 | enc(str[2])
        enc(char) is:  0-25 for A-Z
                      26-35 for 0-9
                      36-44 for $ & # @ ! % - _ /  respectively

        This is normally 'DBF' but the /e parameter to MME can be used to
        change it.

0xDA:   Bits 0-4:  Channel handle of OBJ file
        Bits 5-15: Total size of modules (header word 0x0E << 5)
0xDB:   0 if beeper enabled, else disabled.
0xE7:   System statistics: #outc
0xE8:   System statistics: #outs
0xE9:   System statistics: #curpos
0xEA:   System statistics: #disp
0xEB:   System statistics: #xdisp
0xEC:   System statistics: #gets
0xED:   System statistics: #sets
0xEE:   System statistics: #hsets
0xEF:   System statistics: #vsets