; Z88 CamelForth

; Based on CamelForth for the Zilog Z80 (c) 1994 Bradford J. Rodriguez
; Converted to the Zilog Macro Assembler by D. Beattie Jr. (1998)
; Widely extended and optimised, with Z88-specific words added,
; by Garry Lancaster 1999-2001. Converted to Z80asm assembler 2001.

; Since Z80Asm doesn't support macros at the time of writing, macro
; conversion is done in a pre-assembly process using an ANS Forth
; program, EXPMACROS.FTH.
; To assemble the binary, load the macro source file into an ANS Forth
; (GForth or Z88 CamelForth, for example) and type:
;   S" z88camel.asm" expmacros camel.prj
; The output file may then be assembled with Z80Asm:
;   z80asm -b z88camel.asm
; With GForth on a Unix system, you can simply execute cfmake to do all
; this for you. Similarly, cfmake.bat on DOS/Windoze systems with GForth.

; The EXPMACROS.FS file contains the following macros, and can easily
; be extended or altered:

; Forth header macros:
;  head label,namelength,name,action,immed,fast
;  nohead label,action
;  envhead namelength,name,size
;    label  = assembler name for this word
;    length = length of name field
;    name   = Forth's name for this word in defm format (must not include comma)
;    action = code routine for this word (eg docolon,docode,docon,docreate...)
;    immed  = 0 for normal words, <>0 for immediate words
;    fast   = length of "fast" code to copy (or 0)
;    size   = size (in CELLS) of environment variable data

; Other macros:
;  next		: compiles jp next_code
;  nexthl	; compiles jp nexthl_code (if IP already in HL)
;  innext	; compiles inline code for NEXT
;  endforth	; sets end of dictionary and environment variables

; Direct-Threaded Forth model for Zilog Z80
; 16 bit cell, 8 bit char, 8 bit (byte) adrs unit
;    Z80 BC = Forth TOS (top Param Stack item)
;        HL =       W    working register
;        DE =       IP   Interpreter Pointer
;        SP =       PSP  Param Stack Pointer
;        IX =       RSP  Return Stack Pointer
;        userst =   UP   User area Pointer
;    A, alternate register set = temporaries

; Headers are laid out in memory as:
; lfa:   defw link	; link to NFA of previous word
; nfa:   defb length,name ; name field (link points to start of previous)
;	 defb immed/fast ; bit 7=immediate flag; bits 6-0=fast code length
; cfa:	 call action	; unless action=docode (code starts here)
; pfaa:	 defw pfa	; not present for docode,docon,docolon
; pfa:	 <typespecific> ; may be elsewhere in memory (pointer to it above)

; "Headerless" words *do* include the immed/fast byte prior to the CFA, but
; this is always set to zero (prevents things like S" working in fast code).

; >BODY only works for words with a pfaa, but since the ANS standard only
; requires it to work for CREATEd definitions, this isn't a problem.


; Defining Words
; ==============
;
; Z88 CamelForth provides a large number of defining words. Since definitions
; may be split between namespace (containing the headers up to and including
; pfaa above) and dataspace, it's worth summarising these:
;
; Defining words which require contigious namespace & dataspace (all of these
; create definitions consisting purely of static, initialised data). Exception
; -4093 will be generated if this is not the case:
;  :
;  :NONAME
;  CODE
;  CONSTANT
;  FCODE
;  MARKER
;  PKGCALL
;  VOCABULARY
;
; Defining words which may have separate namespace & dataspace (if dataspace
; is uninitialised RAM, then definitions must be initialised before use):
;  CREATE
;  DEFER
;  VALUE
;
; Special case defining words:
;  MEMPOOL		Namespace & dataspace must be the same, but some
;			uninitialised space is always reserved in RAM
;  VARIABLE		Namespace may be anywhere; dataspace is always
;			specifically set to RAM
;  TASK:		Namespace may be anywhere; dataspace is always
;			specifically set to RAM
;
; Exceptions
; ==========
; The system generates the following exceptions in accordance with ANS Forth:
;	-1	ABORT
;	-2	ABORT"
;	-13	undefined word
;	-35	invalid block number
;	-49	search-order overflow
; Additionally, it may generate the following system-dependent exceptions:
;	-4095	word cannot be "fast"-compiled
;	-4094	input nesting exception
;	-4093	non-contigious compilation spaces
;	-4092   invalid buffer allocation with BLKS
; -(256+OZerr)	OZ error (also returned as iors by file-handling words)
; -(512+pkgid)	Package not found

