MC64 — A 64-Bit Stack Machine

Instruction-Set Specification, derived from the Turbo Modula-2 MCode bytecode

MC64 is a 64-bit generalization of the MCode virtual machine that Borland Turbo Modula-2 for CP/M executed on Z80. Where MCode/16 is a 16-bit word-addressed stack machine with all scalars 16 bits wide, MC64 keeps the stack slot (word) at 64 bits but preserves Modula-2's type ladder: CARDINAL and INTEGER are 32 bits, SET is 64 bits, LONGINT and LONGCARD are 64 bits, REAL is a 64-bit float and LONGREAL is a 128-bit quad.

The 256-entry opcode map is preserved 1:1. The scalar word-op families (0A0H–0BFH and the checked forms) now operate on the 32-bit types; the "long"/"dword" families (0C5H–0CCH) operate on the 64-bit LONGINT type. Unsigned 64-bit (LONGCARD) arithmetic is provided by the extended sub-dispatch (§10.2).

1. Naming and document purpose

word (slot) = 8 bytes = 64 bits — the unit of the stack, frame cells and global cells.
scalar = a typed value held in one slot: 32-bit types (CARDINAL, INTEGER, and 8-bit BYTE/CHAR/BOOLEAN) or 64-bit types (LONGINT, LONGCARD, SET, REAL, pointer).
quad = two slots = 16 bytes = 128 bits (the LONGREAL type).
Operands that in MCode/16 were 16-bit words are here 64-bit words; byte operands stay bytes unless stated otherwise.

This document is the normative reference for a VM implementation (e.g. as a C port) and for a compiler code generator that emits MC64.

2. Memory model

Flat, byte-addressable address space; all addresses are 64-bit little-endian.
Basic storage unit is the byte; the machine word is 8 bytes; words are naturally aligned (address % 8 == 0) unless stated otherwise.
Little-endian everywhere, including stack entries, code operands and multibyte values.

Memory layout convention (shared by the loader, not enforced by the ISA):

high address
+-----------------------------+  ^
|      stack region           |  |  grows DOWN toward globals/heap
|  (SP moves toward lower adr)|
+-----------------------------+
|      heap region            |  |
+-----------------------------+  |  grows UP (ALLOCATE/MARK/RELEASE)
|      module images + globals|
+-----------------------------+  v
|      system tables          |
low address

The evaluation stack and the heap share the middle; the loader places module images at low addresses and lets the stack come down from the top.

3. Registers / machine state

Register	Meaning
`IP`	instruction pointer — byte address of next opcode
`SP`	stack pointer — byte address of the top word (lowest used)
`FP`	frame pointer — base of the current activation frame
`GP`	global pointer — base of the current module's data window
`OFP`	outer frame pointer — static chain / display link
`MTBL`	module table — `MTBL[i]` = data base of loaded module `i`

The stack grows down: Push(w) = SP -= 8; *(u64*)SP = w.

4. Data types

Modula-2 type	Width	Stack slots	Notes
BYTE, CHAR, BOOLEAN	8 bits	1 slot	held in the low bits of a slot
CARDINAL	32 bits	1 slot	unsigned arithmetic, zero-extended
INTEGER	32 bits	1 slot	two's complement, sign-extended
SET	64 bits	1 slot	bit set, elements 0..63
LONGINT	64 bits	1 slot	two's complement signed arithmetic
LONGCARD	64 bits	1 slot	unsigned 64-bit arithmetic (new)
REAL	64 bits	1 slot	IEEE 754 binary64 (double)
LONGREAL	128 bits	2 slots	IEEE 754 binary128 (quad)
pointer/address	64 bits	1 slot	byte address

Storage convention: stack slots are always 64 bits. 32-bit values live in the low 32 bits of their slot — CARDINAL is kept zero-extended, INTEGER is kept sign-extended — while SET and the 64-bit types occupy the full slot. Conversion between a 32-bit type and a 64-bit type is a value no-op. ALL loads and stores move a full slot; the width is a semantic property of the arithmetic and comparison opcodes, not of memory access.

Stack representation of a quad (little-endian):

 memory:  [ low word ... high word ]      low word on top (at SP)

Push order for a quad constant or a quad load: high word first, low word last, so the low word ends up on top of the stack.

5. Stack and frames

One stack holds evaluation data and activation frames.

5.1 Frame layout

              byte offset from FP               stack slot
  FP - N*8  ........  first local word           FP[-N]
  FP - 8    ........  last (shallowest) local    FP[-1]
  FP + 0    ........  OPF (outer frame pointer)  FP[0]
  FP + 8    ........  OLD FP (dynamic link)      FP[1]
  FP + 16   ........  return IP                  FP[2]
  FP + 24   ........  parameter 1                FP[3]
  FP + 32   ........  parameter 2                FP[4]
  ...

Locals use negative word offsets: FP[-1], FP[-2], … The last reserved word (adjacent to the frame link) is offset -1.
Parameters use positive word offsets: parameter k is at FP[k+2].
The caller pushes arguments in reverse declaration order (last parameter pushed first), so parameter 1 is the deepest argument and lands at FP[3].

5.2 Call sequence

  ; evaluate actuals, push them (right to left)
  PROCCALL n                ; push return IP, jump to proc n  (OFP set as needed)
  ENTER k                   ; callee prologue (below)
  ...
  LEAVE0 / PROC_LEAVE n     ; callee epilogue (below)

ENTER k:

  push OLD FP; push OFP ; FP := SP          ; NewFrame
  push IP                                   ; procedure start address
  Reserve( (255-k) * 8 )                    ; locals, in bytes (k=0FFH => none)

PROC_LEAVE n (and the leave family):

  SP := FP                  ; discard frame + locals
  OFP := pop                ; outer frame pointer
  FP  := pop                ; OLD FP (restore caller FP)
  IP  := pop                ; return address
  drop n words              ; discard parameter area (n is 7-bit; see below)
  if (bit 7 of n) and (OFP ≠ NIL): GP := OFP   ; re-enter outer module

Function returns:

FCT_LEAVE n: res := pop; PROC_LEAVE n; push res
LONGREAL_FCT_LEAVE n: same with a quad (two words) preserved across the leave.

The low 7 bits of n in leave opcodes count words to drop from the caller's parameter area. Bit 7 is a flag: when set the procedure returns into its outer (statically enclosing) module, so GP is reloaded from OFP.

6. Addressing families

Family	Base	Word offset n from
Local	`FP`	immediate (s8) or tiny code
Global	`GP` (current module window)	immediate (u8) — `GP[n]`
Extern	`MTBL[moduleNumber]`	`mod` and `var` operands
Indirect	a pointer popped from the stack	immediate (u8) — `*(ptr + n)`
Indexed	a pointer popped from stack + index popped from stack	`*(ptr + index)`

Word offset n means byte offset n*8. Exceptions: the indexed byte ops (0DH/1DH) address single bytes (CHAR/BYTE arrays, strings), and the indexed quad ops (0FH/1FH) address two-slot LONGREAL elements.

The GP window is an array of at least 65536 words; modules loaded so far live in it. MTBL is a system-wide array of 256 64-bit module data bases. EXTERN mod,var operations read MTBL[mod][var].

7. Modules, procedures and linkage

7.1 Module descriptor (in-memory)

ModuleDesc (offsets are image-relative; u64 fields little-endian):
   0      dependencies : ARRAY[0..31] OF ADDRESS   ; 256 bytes (module base pointers)
   256    link         : ADDRESS                   ; next module in chain
   264    name         : ARRAY[0..15] OF CHAR      ; 16-char, NUL-padded
   280    loadAddr     : ADDRESS                   ; base of module data image
   288    checksum     : u32   (32-bit; see §8.3 for the coverage rule)
   292    flags        : u8    (bit0 OVERLAY, bit1 Z80/NATIVE, bit2 TOINIT, bit3 RECURSE)
   293    varCount     : u8    (number of global variable entries)
   294    depCount     : u8    (number of dependencies)
   295    pad          : u8    (reserved, zero)
   296    procsAddr    : ADDRESS                      ; location of the proc table
   304    varSizes     : varCount × ADDRESS   (u64 global variable sizes in bytes)

The descriptor lives at image offset 0 (i.e. immediately after the 64-byte file header). In a single-module file the whole image is a bare descriptor + code + data, so moduleStart (file header, §8.1) is taken as 0.

7.2 Procedure address resolution

Each module has a procedure table at procsAddr: N contiguous 64-bit relative byte offsets, one per procedure.

procedureAddress(k) = procsAddr + k*8  +  (i64) table[k]

The offset is relative to the end of the entry cell, so entry 0 can point directly after its own cell. The table consecutive cells live just below (or beside) the module data; procsAddr is fixed up by the loader.

7.3 External calls

EXTERN_CALL mod,proc:

  OFP := GP                 ; remember current module
  GP  := MTBL[mod]          ; switch to callee module
  push IP
  IP  := procedureAddress(mod, proc)

EXTERN_CALL1 (address+proc number on the stack) does the same with procsNum = pop; modBase = pop; GP = modBase.

8. Loader and on-disk format

A module file ("*.MC4") holds one or several linked modules plus their dependencies.

8.1 File header (64 bytes)

Offset	Size	Field	Meaning
0	8	magic	`"MC64\0\0\0\0"` (constant `0x_4D_43_36_34`)
8	8	fileSize	bytes of the image block (not header)
16	8	moduleStart	offset of the module descriptor within the image
24	8	depsOffset	offset of the dependency table within the image
32	8	nbDependencies	number of dependencies
40	24	reserved	zero

8.2 Dependency record (32 bytes each)

Size	Field	Meaning
16	name	module name, NUL-padded
8	version	import version (0 = any)
8	location	offset of the fixup that must point at the module data base after load

8.3 Load sequence

LoadWithDependencies(modName, referencer, version):
  open file; read header
  origin := allocAddr; load image blob at origin
  read dependency records (depsOffset + i*32)
  walk the module chain starting at origin + moduleStart:
      add origin to loadAddr, procsAddr, each non-NIL dependency pointer
      set RECURSEFLAG
  verify checksum of the requested (last) module
  if not already loaded:
      relocation pass: for each fixup pair (location,count) in the descriptor,
          add origin to the target pointed by the (relocated) location
      translate dependency fixups: moduleBase := loadModule(dep); *(location+origin) := moduleBase
  init module globals (varCount × sizes), zero-filled

Checksum rule (as implemented): the module checksum is the plain 32-bit sum of the image bytes (file offsets HeaderSize..fileSize-1) excluding the four checksum bytes themselves (file 352..355 = image 288..291). For the reference loader the image is placed at ArenaBase (1 MiB) with the descriptor at image offset 0, and the module's data window (dataWin) is allocated right after the image, 8-byte aligned, and zero-filled; dependencies, link and multi-module relocation are currently unsupported (depCount > 0 is rejected).

8.4 Global variable allocation

After loading, the loader allocates varSize bytes for each entry, fills them with zeros and records the allocated base in the module descriptor's var-size table slot.

9. Execution

9.1 Run loop

Run:
  loop
    opcode := NextByte()
    dispatch opcode
  loop forever

NextByte reads one byte and advances IP. NextWord reads a 64-bit little-endian word (8 bytes). NextSigned reads a signed 8-bit value.

9.2 Exceptions

Exception	Raised by
IllegalInstruction	opcode 00
Unimplemented	opcodes 01, 87, native-stub services
Overflow	checked arithmetic (0C0H–0C2H, 0D0H–0D1H)
RangeError	0DAH, 0DBH, 0DCH, 0DDH
DivideByZero	DIV/MOD with zero divisor
StackOverflow	reserve crossing the stack/heap limit
OutOfMemory	ALLOCATE breathing the stack
StringTooLong	copy_string overflow
LoadError	loader (module not found / version conflict)

A raising opcode aborts the current Run and unwinds to the nearest handler (register via RAISE/handler services). If no handler exists, the VM terminates the current module and reports the exception record (name, kind, IP), then returns to the caller of Call. Concurrency/process support (TRANSFER, NEWPROCESS) is out of scope for the baseline machine and raises Unimplemented.

9.3 Host interface (0C3H `SYSTEM`)

SYSTEM is the escape hatch to the host environment (successor to the CP/M BDOS):

  id    := pop           ; service number
  param := pop           ; address (or scalar)

Baseline services (implementation provided by the VM):

id	Service
0	EXIT (param = status ignored)
1	write NUL-terminated string at param
2	read line into buffer at param
3+	host-defined extensions

Service 2 (read line) pulls characters from the host standard input up to (but not including) the line mark, or until end of input. The bytes are stored at param, a NUL terminator is appended, and the byte count read (excluding the terminator) is pushed onto the operand stack. An empty line or immediate end of input pushes 0. A guest therefore reads a line with: load_imm_word buf; load_imm_byte 2; system; and may echo it straight back with service 1 because the buffer is NUL-terminated.

10. Sub-opcode dispatches

Two opcodes delegate to a secondary byte:

10.1 Sub-opcode `0x12` — LONGREAL (quad) operations

sub	mnemonic	operands	effect
00	load_local_q	s8 n	push quad `FP[n]`..`FP[n+1]` (local)
01	load_global_q	u8 n	push quad `GP[n]`..`GP[n+1]` (global)
02	load_i_q	u8 n	pop p; push quad `p[n]`..`p[n+1]` (indirect)
03	load_extern_q	mod, var	push quad `MTBL[mod][var..var+1]`
04	store_local_q	s8 n	store quad of stack into local
05	store_global_q	u8 n	store quad into global
06	store_i_q	u8 n	pop p; store quad into `p[n..]`
07	store_extern_q	mod, var	store quad into external module
08	load_indexed_q	—	pop i (index), pop p; push quad `p[i]`
09	store_indexed_q	—	pop q (quad); pop i; pop p; store quad `p[i]`
0A	quad_fct_leave	u8 n	q:=pop; proc_leave n; push q (quad fct leave)
others	illegal

(0x40 0x12 is reserve_string, see extended table.)

10.2 `0x40` — extended operations

sub	mnemonic	effect
00	drop	pop 1 word
01	enter_monitor	no-op (host hook for preemption)
02	leave_monitor	no-op
03	long_negate	pop LONGINT; push -LONGINT (64-bit signed negate)
04	build_field_mask	pop hi; pop lo; push (1<<hi) - (1<<lo)
05	ALLOCATE	pop size; pop p; alloc; *p := block
06	DEALLOCATE	pop size; pop p; free p; p := NIL
07	MARK	pop p; *p := heapMark
08	RELEASE	pop p (mark addr); release; *p := NIL
09	FREEMEM	push bytes free
0A	TRANSFER	unimplemented (processes)
0B	IOTRANSFER	unimplemented
0C	NEWPROCESS	unimplemented
0D	BIOS	host call: fct:=pop; param:=pop; BIOS(fct,param)
0E	MOVE	pop size; pop dst; pop src; memcpy(dst,src,size)
0F	FILL	pop value; pop size; pop addr; memset(addr,value,size)
10	INP	host I/O read port
11	OUT	host I/O write port
12	reserve_string	see §13
13	assert	assertion: pop 0 → raise RangeError
14	uc_less	pop b; pop a; push (a < b) (LONGCARD)
15	uc_less_eq	pop b; pop a; push (a <= b) (LONGCARD)
16	uc_greater	pop b; pop a; push (a > b) (LONGCARD)
17	uc_greater_eq	pop b; pop a; push (a >= b) (LONGCARD)
18	uc_add	pop b; pop a; push (a + b) mod 2^64 (LONGCARD)
19	uc_sub	pop b; pop a; push (a - b) mod 2^64 (LONGCARD)
1A	uc_mul	pop b; pop a; push (a * b) mod 2^64 (LONGCARD)
1B	uc_div	pop b; pop a; push (a DIV b) (raise DivideByZero)
1C	uc_mod	pop b; pop a; push (a MOD b) (raise DivideByZero)
1D	uc_to_real	pop LONGCARD; push REAL (rounded; optional)
1E	real_to_uc	pop REAL; push LONGCARD (truncated; optional)
others		illegal

11. Instruction set reference

Notation: stack effects are written bottom…top → result. pop reads the top word. u8/i8/u64/i64 are operand encodings. Multi-word quads are noted as q.

11.1 0x00–0x1F — loads, stores, params, indexed

Hex	Mnemonic	Operand	Effect
00	reserved	—	raise IllegalInstruction
01	RAISE	—	unimplemented (see §9.2)
02	load_proc_addr	u8 n	push procedureAddress(current_mod, n)
03–07	load_param (1–5)	—	push `FP[3..7]` (param 1..5)
08	load_local_dw	i8 n	push slot `FP[n]` (legacy 64-bit slot / LONGINT)
09	load_global_dw	u8 n	push slot `GP[n]` (LONGINT/LONGCARD)
0A	load_stack_dw	u8 n	pop p; push slot `p[n]` (64-bit)
0B	load_extern_dw	mod,var	push slot `MTBL[mod][var]` (64-bit)
0C	load_extern_w	nibble	push slot `MTBL[m][n]` (nibble m,n)
0D	load_indexed_byte	—	pop i; pop p; push (u8)`p[i]`
0E	load_indexed_w	—	pop i; pop p; push `p[i*8]` (one slot)
0F	load_indexed_q	—	pop i; pop p; push quad `p[i8]`,`p[i8+1]` (LONGREAL)
10	load_outer	—	push `FP` of enclosing frame (display +1)
11	load_outer_n	u8 n	push frame pointer n display-steps up
12	LONGREAL op	sub	secondary dispatch (§10.1)
13–17	store_param (1–5)	—	pop; `FP[3..7]` := value
18	store_local_dw	i8 n	pop; store slot into `FP[n]`
19	store_global_dw	u8 n	pop; store slot into `GP[n]`
1A	store_stack_dw	u8 n	pop; pop p; store slot into `p[n]`
1B	store_extern_dw	mod,var	pop; store slot into `MTBL[mod][var]`
1C	store_extern_w	nibble	pop; store slot into `MTBL[m][n]`
1D	store_indexed_byte	—	pop v; pop i; pop p; `p[i] := v (byte)`
1E	store_indexed_w	—	pop v; pop i; pop p; `p[i*8] := v`
1F	store_indexed_q	—	pop q; pop i; pop p; store quad at `p[i*8]`

11.2 0x20–0x3F — stack ops, local/global loads & stores, copies

Hex	Mnemonic	Operand	Effect
20	dup	—	push top
21	swap	—	exchange top two words
22–2B	load_local_n	—	push `FP[-(op & 0x0F)]` (offsets +2..−11)
2C	load_local	i8 n	push `FP[n]` (n<0 local, n>0 param)
2D	load_global	u8 n	push `GP[n]`
2E	load_stack	u8 n	pop p; push `p[n]`
2F	load_extern	mod,var	push `MTBL[mod][var]`
30	copy_block	—	pop size; pop src; pop dst; memcpy
31	copy_string	—	pop srcSize; pop dstSize; pop src; pop dst; copy NUL-terminated
32–3B	store_local_n	—	pop; `FP[-(op & 0x0F)] := value` (s2..−11)
3C	store_local	i8 n	pop; `FP[n] := value`
3D	store_global	u8 n	pop; `GP[n] := value`
3E	store_stack	u8 n	pop; pop p; `p[n] := value`
3F	store_extern	mod,var	pop; `MTBL[mod][var] := value`

11.3 0x40–0x5F — extended dispatch, global 2–15

Hex	Mnemonic	Effect
40	extended	secondary dispatch (§10.2)
41	load_stack_d0	pop p; push slot `p[0]` (alias of 60H, retained)
42–4F	load_global_n	push `GP[op & 0x0F]` (offsets 2–15)
50	end_program	return control to the loader/kernel
51	store_stack_d0	pop v; pop p; store slot `p[0]` (alias of 70H)
52–5F	store_global_n	pop; `GP[op & 0x0F] := value` (2–15)

11.4 0x60–0x7F — indirect loads/stores (offsets 0–15)

Hex	Mnemonic	Effect
60–6F	load_i_n	pop p; push `p[op & 0x0F]` (one slot)
70–7F	store_i_n	pop v; pop p; `p[op & 0x0F] := v` (one slot)

11.5 0x80–0x9F — addresses, leaves, strings, immediates

Hex	Mnemonic	Operand	Effect
80	load_local_addr	i8 n	push byte addr `FP + n*8`
81	load_global_addr	u8 n	push byte addr `GP + n*8`
82	load_stack_addr	u8 n	pop p; push `p + n*8`
83	load_extern_addr	mod,var	push byte addr `MTBL[mod] + var*8`
84	proc_leave	u8 n	leave: drop `n & 0x7F` words; re-enter if bit7
85	fct_leave	u8 n	res:=pop; proc_leave n; push res
86	longfct_leave	u8 n	q:=pop; proc_leave n; push q (quad)
87	asmcode	u8 n	native code block; unimplemented in baseline
88–8B	leave (0..3)	—	leave, drop 0..3 words, bit7 set (outer return)
8C	call_rel	u8 n	push `IP`; `IP += n` (pc-relative string ptr)
8D	load_imm_byte	u8	push zero-extended u8
8E	load_imm_word	u64	push 64-bit immediate (8 bytes)
8F	load_imm_quad	16 bytes	push quad constant (low word on top)
90–9F	load_imm 0–15	—	push small constant `op & 0x0F`

11.6 0xA0–0xBF — comparisons, integer arithmetic, conversions

Hex	Mnemonic	Effect
A0	equal	pop b; push (pop = b) (full slot, any width)
A1	not_equal	pop b; push (pop # b)
A2	uless	pop b; push (pop < b) (CARDINAL, 32-bit)
A3	ugreater	pop b; push (pop > b) (CARDINAL)
A4	uless_eq	pop b; push (pop <= b) (CARDINAL)
A5	ugreater_eq	pop b; push (pop >= b) (CARDINAL)
A6	add	pop b; push (pop + b) (CARDINAL, mod 2^32)
A7	sub	pop b; push (pop - b) (CARDINAL, mod 2^32)
A8	umul	pop b; push (pop * b) (CARDINAL)
A9	udiv	pop b; push (pop DIV b) (raise DivideByZero)
AA	umod	pop b; push (pop MOD b) (raise DivideByZero)
AB	eq0	push (pop = 0)
AC	inc	push (pop + 1) (32-bit)
AD	dec	push (pop - 1) (32-bit)
AE	add_imm	u8 n; push (pop + n) (CARDINAL)
AF	sub_imm	u8 n; push (pop - n) (CARDINAL)
B0	shl_imm	u8 n; push (pop << n) (CARDINAL, logical)
B1	shr_imm	u8 n; push (pop >> n) (logical)
B2	iless	pop b i32; push (pop < b) (INTEGER)
B3	igreater	pop b i32; push (pop > b) (INTEGER)
B4	iless_eq	pop b i32; push (pop <= b) (INTEGER)
B5	igreater_eq	pop b i32; push (pop >= b) (INTEGER)
B6	not	push (¬ bool(pop))
B7	complement	push (0xFFFFFFFF − pop) (32-bit bitwise NOT)
B8	imul	pop b i32; push (pop * b) (INTEGER)
B9	idiv	pop b i32; push (pop DIV b) (raise DivideByZero)
BA	long_to_card	pop LONGINT; push CARDINAL (low 32 bits, zero-extended)
BB	long_to_int	pop LONGINT; push INTEGER (low 32 bits, sign-extended)
BC	abs	pop i32; push
BD	int_to_long	pop INTEGER; push LONGINT (sign-extended)
BE	long_to_real	pop LONGINT; push REAL (rounded)
BF	real_to_long	pop REAL; push LONGINT (truncated)

Notes: CARDINAL-LONGCARD and LONGCARD-LONGINT widenings are value no-ops (all are one slot; see §4). Because 32-bit errors would be silent, CARDINAL/INTEGER arithmetic uses the checked forms of §11.7 when CHECK-range diagnostics are enabled.

11.7 0xC0–0xDF — checked/long/real arithmetic, switch, short-circuit

Hex	Mnemonic	Effect
C0	uadd_checked	pop b; push (pop + b) (CARDINAL; raise Overflow on wrap)
C1	usub_checked	pop b; push (pop - b) (CARDINAL; raise on borrow)
C2	umul_checked	pop b; push (pop * b) (CARDINAL; raise on overflow)
C3	system	host call (§9.3)
C4	string_comp	see §12.1
C5	long_compare	pop b; pop a; push (a>b), push (a<b) (LONGINT, signed 64)
C6	long_add	pop b; pop a; push a + b (LONGINT)
C7	long_sub	pop b; pop a; push a − b
C8	long_mul	pop b; pop a; push a × b
C9	long_div	pop b; pop a; push a DIV b (signed; raise on 0)
CA	long_mod	pop b; pop a; push a MOD b (signed; raise on 0)
CB	not_zero	push (pop # 0)
CC	long_abs	pop a; push
CD	switch	§12.2 (case tables)
CE	jump_stack	pop; IP := value (computed jump/return)
CF	push_code_addr	u64; push (IP - 1 + off) (pc-relative)
D0	iadd_checked	pop b i32; push (pop + b); raise Overflow (INTEGER)
D1	isub_checked	pop b i32; push (pop - b); raise Overflow (INTEGER)
D2	reserve	pop size; check limit; SP -= size; push new SP
D3	reserve_string	see §13
D4	enter	u8 k — prologue, reserve (255−k)*8 bytes
D5	real_compare	pop r2; pop r1; push r1>r2, push r1<r2 (REAL)
D6	real_add	pop r2; pop r1; push r1+r2 (REAL)
D7	real_sub	pop r2; pop r1; push r1−r2
D8	real_mul	pop r2; pop r1; push r1×r2
D9	real_div	pop r2; pop r1; push r1/r2
DA	urange_check	pop low; pop size; Top in [low, low+size]? (CARDINAL)
DB	irange_check	pop low i32; pop size; Top in [low, low+size]? (INTEGER)
DC	limit_check	u8 n; if Top() > n raise RangeError (CARDINAL)
DD	check_positive	if (i32)Top() < 0 raise RangeError (INTEGER)
DE	and_jp	u8 n; if not pop then push false; IP += n
DF	or_jp	u8 n; if pop then push true; IP += n

11.8 0xE0–0xFF — jumps, bit sets, calls

Hex	Mnemonic	Operand	Effect
E0	jp	i64	IP += rel
E1	jpfalse	i64	if not pop then IP += rel
E2	jp_fwd	i8	IP += rel
E3	jpfalse_fwd	i8	if not pop then IP += rel
E4	jp_back	u8	IP -= rel
E5	jpfalse_back	u8	if not pop then IP -= rel
E6	bit_or	—	pop b; push bitset(pop) ∪ bitset(b)
E7	bit_in	—	pop b; push (pop ∈ bitset(b))
E8	bit_and	—	pop b; push bitset(pop) ∩ bitset(b)
E9	bit_xor	—	pop b; push bitset(pop) △ bitset(b)
EA	power2	—	push (1 << pop)
EB	extern_proc_call	—	n:=pop; base:=pop; call via MTBL (base=addr)
EC	nested_call	u8 n	call proc n with OFP = FP (static nesting)
ED	proc_call	u8 n	call proc n, OFP = NIL
EE	call_with_frame	u8 n	pop f; call proc n with OFP = f
EF	extern_call	mod,proc	call proc in module `mod` (2 operands)
F0	extern_call_nib	nibble	call proc `n` in module `m` (high/low nibbles)
F1–FF	call 1..15	—	call proc `op & 0x0F`, OFP = NIL

Jump offsets are relative to the address after the operand(s). All jumps except E0/E1 are byte offsets; E0/E1 carry a full 64-bit signed offset.

SET operations (0E6H–0EAH) operate on the 64-bit SET type; element indices are 0..63 and power2 computes 1 << pop (mod 2^64).

12. Complex instructions

12.1 String compare (0C4H)

pop size2; pop size1        ; buffer lengths (bytes)
pop str2; pop str1
compare char-by-char up to a NUL terminator or exhausted size
push (str1 > str2)          ; boolean
push (str1 < str2)          ; boolean

The caller consumes the two booleans (typically or_jp / and_jp to build lexicographic ordering tests).

12.2 Switch / case statement (0CDH)

Encoding after the opcode:

lowBound        u64
highBound       u64
retOffset       i64   ; reserved; must be 0
jumpTable       (highBound − lowBound + 1) × i64

Dispatch:

N := high − low + 1
first := address of the first table cell
endOfTable := first + N*8
if value < lowBound or value > highBound:
    IP := endOfTable                       ; default code follows the table
else:
    cell := first + (value − lowBound)*8
    off  := (i64)*cell
    if off < 0:                            ; call-switch form
        push endOfTable                    ; return address after the table
    IP := cell + 8 + off

Entry offsets are relative to the end of their own cell; a negative offset denotes a call-switch (each case is a procedure, returning to the code after the table). retOffset is retained for encoding compatibility with MCode/16 and must be 0.

12.3 `reserve_string` (0D3H and `0x40 0x12`)

src     := pop                  ; byte address of the string data
nBytes  := pop
nWords  := (nBytes + 7) DIV 8
copy nWords words from src onto the stack (stack limit checked)
push the address of the copy    ; top of the copied region

Used by the compiler to materialize a local owned copy of a string constant (the constant itself lives in the code area at a pc-relative address).

13. Initialization sequence

Call(modName):
  save current module chain and caller frame
  MARK(heap)
  LoadWithDependencies(modName)
  for each newly loaded module:
      allocate + zero global variables
  for each module flagged TOINIT, in load order:
      GP := module base
      FP := fresh frame            ; reference frame
      IP := procedureAddress(module, 0)        ; its initializer
      Run()
  RELEASE(heap mark)
  restore caller module chain

The last module initialized is the requested one; this is how the system boots the target module and returns to the shell when it end_programs.

14. Differences from MCode/16 (migration notes)

MCode/16	MC64
word = 16 bits, address space 64 KB	word = 64 bits, address space 2^64
scalar types 16 bits; LONGINT/REAL 32 bits (2 words); LONGREAL 64 (4 words)	CARDINAL/INTEGER 32 bits; SET/LONGINT/LONGCARD 64 bits; REAL 64-bit float; LONGREAL 128 bits (2 slots)
byte/nibble operands (bytes, # args, depths)	byte operands unchanged; all word operand fields widened 2→8 bytes
local addressing in bytes (F+2n)	local addressing in words (FP ± n*8)
global window 64 K words, module table in top entries	window of ≥64 K words + dedicated 256-slot module table `MTBL`
module baseline tables relative to base−2/−18/−14	explicit `procsAddr`, `loadAddr`, `dependencies[]` fields (module descriptor)
`Enter` reserves 255−n bytes	`Enter` reserves (255−n)×8 bytes
immediates: byte / 2-byte word / 4-byte dword	byte / 8-byte word / 16-byte quad
switch tables: 16-bit offsets, +8000H unsigned trick	64-bit signed offsets, plain unsigned compare, `retOffset` reserved
proc table: `base-2` cell, +1+offset	`procsAddr` + k*8 + offset
BDOS 0C3H	`SYSTEM` host-call ABI (§9.3)
`.MCD` (no magic, CP/M 8-char names)	`.MC4` (magic header, 16-char names, 64-bit fields)

All 256 opcodes keep their MCode/16 position in the map; only operand widths and the scalar→(32/64/128-bit) mapping differ. The scalar word-op families (0A0H–0BFH) are 32-bit; the "long" families (0C5H–0CCH) are 64-bit; LONGCARD arithmetic is provided by the extended sub-dispatch (§10.2).

15. Minimal encoding example

A procedure P(x: CARDINAL): CARDINAL that computes 2*x + 1 (32-bit CARDINAL ops):

  d4 fe      enter -2                     ; prologue: reserve (255-0xFE)*8 = 8 bytes (1 slot)
  8d 02      load_imm_byte 2
  3c fe      store_local -2               ; tmp := 2
  03         load_param1                  ; x   (FP[3])
  2c fe      load_local -2                ; tmp
  a8         umul                         ; CARDINAL multiply (32-bit)
  8d 01      load_imm_byte 1
  a6         add                          ; CARDINAL add (32-bit)
  85 01      fct_leave 1                  ; return; drop 1 word (the parameter)

Provenance: transcribed from the reverse-engineering of Borland Turbo Modula-2 (CP/M Z80), the MCode_specification bytecode interpreter in Reversing-Turbo-Modula2.

16. GNU Modula-2 (ISO) implementation notes

The reference interpreter in mc64/ is written in pure ISO Modula-2 and compiled exclusively with gm2 -fiso. These notes record the GNU M2 idioms and constraints the source relies on.

16.1 Build rules

Every module is compiled with gm2 -fiso -c <module>.mod.
Only a program module is passed to the link step; library modules are given as pre-compiled .o. Passing several .mod files at once makes gm2 emit one main per module and the link fails on duplicate main.
Deterministic build: Memory Local Global Stack Instruction Extended Interpreter Loader2 Console FileIO (each .mod), then MC64.mod and mkdemo.mod, then gm2 -fiso -o mc64 MC64.mod <12 .o> and gm2 -fiso -o mkdemo mkdemo.mod <12 .o>.

16.2 Language constraints observed

AND/OR are Boolean-only: gm2's ISO front end has no integer bitwise AND/OR. Integer bitwise ops are done with a BitOp(a, b, mode) loop (64 iterations of DIV 2^k/MOD 2); bit masking uses MOD/DIV arithmetic (opc MOD 16, (fl DIV 4) MOD 2 for the TOINIT bit). A stray integer AND typically surfaces as a misleading "is not a boolean expression" diagnostic pointed at a VAR declaration several lines earlier.
Ignored function results are errors: a bare Pop () ; (return value discarded) does not compile; always capture into a variable.
Variant records: the tag must be an exhaustive choice; CASE : BOOLEAN OF | TRUE: ... | FALSE: ... works, CASE : CARDINAL OF is rejected ("not all variant record alternatives"). This is the mechanism used to reinterpret a 64-bit slot as REAL/LONGCARD and a 128-bit LONGREAL as two slots.
No import alias: FROM m IMPORT x AS y is a parse error. Name clashes (e.g. IOChan.WriteLn vs a local WriteLn) are avoided by not importing the colliding name (the module writes LF itself).
Set constructors: an inline FlagSet{...} argument can crash gm2 ("internal compiler error: expecting ConstVar symbol"); assign the constructor to a local VAR and pass the variable instead.
Definition modules: an IMPORT must precede EXPORT QUALIFIED.
HALT(n) works under -fiso and is used for fatal host errors (THROW aborts with SIGABRT).

16.3 Host services

No libc: no DEFINITION MODULE FOR "C", no M2PIM legacy modules (Args, UnixArgs, …). Vendor m2pim modules fail to link against -fiso objects.
System.ProgramArgs.ArgChan is not usable in this gm2 build: TextRead on it blocks forever and Look returns a '.' filler instead of endOfInput. The VM therefore boots a fixed boot.mc4 (generated by mkdemo) instead of parsing argv.
File I/O uses StreamFile.Open/Close + IOChan.RawRead/RawWrite (ChanConsts FlagSet{readFlag, oldFlag, rawFlag} / {writeFlag, rawFlag}).
Screens output writes go to the ISO standard output channel (StdChans.StdOutChan) with IOChan.TextWrite; LC real values go out via RealStr.RealToStr.

16.4 Machine representation

Slots are 64-bit Little-Endian, addressed through a 16 MiB static CHAR arena (Memory.ms, MaxMem = 16777216) with byte-assembling readers/writers (ReadSlot/WriteSlot, ReadLong/WriteLong, ReadWord/WriteWord).
The image is loaded at ArenaBase = 1048576 via LoadImage(data, off, dst, n) (images start at file offset 64, hence the source offset parameter). 32-bit descriptor fields (e.g. checksum) must be read with ReadLong, never with the 8-byte reader.
LONGCARD is used for addresses, stack slots and 64-bit arithmetic; untyped literals, H-suffixed hex constants and VAL conversions all compile under -fiso.

mc64-spec.md 41 KB تاريخچه خام