Started cross compiler documentation

Made 4stack, 8086, and MISC Gforth-EC work again

Makefile.in

@@ -528,17 +528,14 @@ kernl64l.fi-:	$(KERN_SRC) kernel/version.fs mach64l.fs $(FORTH_GEN0)
 kernl64b.fi-:	$(KERN_SRC) kernel/version.fs mach64b.fs $(FORTH_GEN0)
 		$(FORTHK) -e 's" mach64b.fs"' $(srcdir)/kernel/main.fs -e "save-cross kernl64b.fi- $(bindir)/gforth-$(VERSION) bye"
 
-kernl-%.fi:	arch/%/mach.fs \
-		$(KERN_SRC) kernel/version.fs $(FORTH_GEN0)
+kernl-%.fi:	arch/%/mach.fs $(KERN_SRC) kernel/version.fs $(FORTH_GEN0)
 		$(FORTHK) -e 's" $<"' $(srcdir)/kernel/main.fs -e "save-cross $@- $(bindir)/gforth-$(VERSION) bye"
 		if [ -f `echo $< | sed s/fs/sh/` ]; \
 		then sh `echo $< | sed s/fs/sh/` $@; \
 		else $(CP) $@- $@; \
 		fi
 
-arch/%/mach.fs:	arch/%/prim.fs
-
-arch/%/prim.fs:	arch/%/asm.fs
+arch/%/mach.fs:	arch/%/prim.fs arch/%/asm.fs
 
 kernl16b.fi:	$(KERNLS)
 		-$(CP) kernl16b.fi kernl16b.fi~

arch/4stack/mach.sh

 #!/bin/sh
 gforth arch/4stack/relocate.fs \
- -e "s\" $1-\" read-gforth s\" ../4stack/${1%%fi}4o\" write-gforth bye"
+ -e "s\" $1-\" read-gforth s\" ../4stack/gforth.4o\" write-gforth bye"
 cp $1- $1

arch/8086/mach.fs

@@ -16,26 +16,15 @@ false Constant bigendian
 
 : prims-include  ." Include primitives" cr s" arch/8086/prim.fs" included ;
 : asm-include    ." Include assembler" cr s" arch/8086/asm.fs" included ;
-: >boot s" ' boot >body into-forth 1+ !" evaluate ;
+: >boot          ." Prepare booting" cr
+    s" ' boot >body into-forth 1+ !" evaluate ;
 
 false Constant NIL
 
 >ENVIRON
 
-false Constant relocate
 true  Constant ec
-false Constant file
-false Constant OS
-false Constant prims
-false Constant floating
-false Constant glocals
-false Constant dcomps
-false Constant hash
-false Constant xconds
-false Constant header
-true  Constant interpreter
 true  Constant crlf
-true  Constant ITC
 \ true Constant has-rom
 
 cell 2 = [IF] 32 [ELSE] 256 [THEN] KB Constant kernel-size

arch/misc/mach.fs

@@ -35,7 +35,7 @@ false Constant NIL  \ relocating
 : asm-include    ." Include assembler" cr s" ~+/arch/misc/asm.fs" included ;
 : >boot
     hex
-    S" $6FF0 SP ! $7FF0 RP ! $7000 2* UP ! ' boot >body IP !" evaluate    
+    S" $6FF0 SP 2* ! $7FF0 RP 2* ! $7000 2* UP 2* ! ' boot >body IP 2* !" evaluate    
     decimal ;
 
 >ENVIRON

arch/misc/prim.fs

@@ -740,11 +740,11 @@ SP 2* Constant SP
 UP 2* Constant UP
 IP 2* Constant IP
 
-c: sp! 2/ sp ! ;
-c: sp@ sp @ 1+ 2* ;
-c: rp@ rp @ 2* ;
-c: rp! r> swap 2/ rp ! >r ;
-c: up@ up @ ;
-c: up! up ! ;
+\ c: sp! 2/ sp ! ;
+\ c: sp@ sp @ 1+ 2* ;
+\ c: rp@ rp @ 2* ;
+\ c: rp! r> swap 2/ rp ! >r ;
+: up@ up @ ;
+: up! up ! ;
 
 include ./key.fs

arch/misc/sim.fs

@@ -47,6 +47,7 @@ variable nesting 0 nesting !
 		\ $15 ram> ." IP: " .#### .hs
 		\ dup CASE [char] : OF 1 nesting +! ENDOF 
 		\ [char] ; OF -1 nesting +! ENDOF ENDCASE
+		[IFDEF] curoff curoff [THEN]
 		dup bl < IF
 		    CASE
 			#cr OF  ENDOF
@@ -54,10 +55,11 @@ variable nesting 0 nesting !
 			[IFDEF] del #bs OF  del  ENDOF [THEN]
 			dup emit  ENDCASE
 		    ELSE  emit  THEN
-		[IFDEF] tflush tflush [ELSE] key? drop [THEN] ;
+		[IFDEF] tflush tflush [ELSE] key? drop [THEN]
+		[IFDEF] curon curon [THEN] [IFDEF] pause pause [THEN] ;
 : tx?>		1 ;
 : rxd>		key [IFDEF] curon curon [THEN] ;
-: rx?>		key? 1 and ;
+: rx?>		key? 1 and [IFDEF] pause pause [THEN] ;
 
 \ Arithmetic
 

cross.fs

@@ -787,7 +787,7 @@ VARIABLE env-current \ save information of current dictionary to restore with en
 
 >ENVIRON get-order get-current swap 1+ set-order
 true SetValue compiler
-true  SetValue cross
+true SetValue cross
 true SetValue standard-threading
 >TARGET previous
 

doc/gforth.ds

@@ -95,7 +95,7 @@ Copyright @copyright{} 1995-1999 Free Software Foundation, Inc.
 @center Bernd Paysan
 @center Jens Wilke
 @sp 3
-@center This manual is permanently under construction and was last updated on 05-Jun-1999
+@center This manual is permanently under construction and was last updated on 31-Dec-1999
 
 @comment  The following two commands start the copyright page.
 @page
@@ -287,7 +287,7 @@ Programming Tools
 
 * Debugging::                   Simple and quick.
 * Assertions::                  Making your programs self-checking.
-* Singlestep Debugger::		Executing your program word by word.
+* Singlestep Debugger::         Executing your program word by word.
 
 Locals
 
@@ -6319,7 +6319,7 @@ doc-span
 @menu
 * Debugging::                   Simple and quick.
 * Assertions::                  Making your programs self-checking.
-* Singlestep Debugger::		Executing your program word by word.
+* Singlestep Debugger::         Executing your program word by word.
 @end menu
 
 @node Debugging, Assertions, Programming Tools, Programming Tools
@@ -11335,7 +11335,7 @@ has the following form:
 
 @cindex primitive source format
 @format
-@i{Forth-name}	@i{stack-effect}	@i{category}	[@i{pronounc.}]
+@i{Forth-name}  @i{stack-effect}        @i{category}    [@i{pronounc.}]
 [@code{""}@i{glossary entry}@code{""}]
 @i{C code}
 [@code{:}
@@ -11362,7 +11362,7 @@ prelude and postlude for each primitive. The final C code for @code{+}
 looks like this:
 
 @example
-I_plus:	/* + ( n1 n2 -- n ) */  /* label, stack effect */
+I_plus: /* + ( n1 n2 -- n ) */  /* label, stack effect */
 /*  */                          /* documentation */
 @{
 DEF_CA                          /* definition of variable ca (indirect threading) */
@@ -11586,7 +11586,11 @@ find numbers for Gforth on various machines in @file{Benchres}.
 @node Cross Compiler, Bugs, Binding to System Library, Top
 @chapter Cross Compiler
 
-Cross Compiler
+The cross compiler is used to bootstrap a Forth kernel. Since Gforth is
+mostly written in Forth, including crucial parts like the outer
+interpreter and compiler, it needs compiled Forth code to get
+started. The cross compiler allows to create new images for other
+architectures, even running under another Forth system.
 
 @menu
 * Using the Cross Compiler::
@@ -11596,6 +11600,119 @@ Cross Compiler
 @node Using the Cross Compiler, How the Cross Compiler Works, Cross Compiler, Cross Compiler
 @section Using the Cross Compiler
 
+The cross compiler uses a language that resembles Forth, but isn't. The
+main difference is that you can execute Forth code after definition,
+while you usually can't execute the code compiled by cross, because the
+code you are compiling is typically for a different computer than the
+one you are compiling on.
+
+The Makefile is already set up to allow you to create kernels for new
+architectures with a simple make command. The generic kernels using the
+GCC compiled virtual machine are created in the normal build process
+with @code{make}. To create a embedded Gforth executable for e.g. the
+8086 processor (running on a DOS machine), type
+
+@example
+make kernl-8086.fi
+@end example
+
+This will use the machine description from the @file{arch/8086}
+directory to create a new kernel. A machine file may look like that:
+
+@example
+\ Parameter for target systems                         06oct92py
+
+    4 Constant cell             \ cell size in bytes
+    2 Constant cell<<           \ cell shift to bytes
+    5 Constant cell>bit         \ cell shift to bits
+    8 Constant bits/char        \ bits per character
+    8 Constant bits/byte        \ bits per byte [default: 8]
+    8 Constant float            \ bytes per float
+    8 Constant /maxalign        \ maximum alignment in bytes
+false Constant bigendian        \ byte order
+( true=big, false=little )
+
+include machpc.fs               \ feature list
+@end example
+
+This part is obligatory for the cross compiler itself, the feature list
+is used by the kernel to conditionally compile some features in and out,
+depending on whether the target supports these features.
+
+There are some optional features, if you define your own primitives,
+have an assembler, or need special, nonstandard preparation to make the
+boot process work. @code{asm-include} include an assembler,
+@code{prims-include} includes primitives, and @code{>boot} prepares for
+booting.
+
+@example
+: asm-include    ." Include assembler" cr
+  s" arch/8086/asm.fs" included ;
+
+: prims-include  ." Include primitives" cr
+  s" arch/8086/prim.fs" included ;
+
+: >boot          ." Prepare booting" cr
+  s" ' boot >body into-forth 1+ !" evaluate ;
+@end example
+
+These words are used as sort of macro during the cross compilation in
+the file @file{kernel/main.fs}. Instead of using this macros, it would
+be possible --- but more complicated --- to write a new kernel project
+file, too.
+
+@file{kernel/main.fs} expects the machine description file name on the
+stack; the cross compiler itself (@file{cross.fs}) assumes that either
+@code{mach-file} leaves a counted string on the stack, or
+@code{machine-file} leaves an address, count pair of the filename on the
+stack.
+
+The feature list is typically controlled using @code{SetValue}, generic
+files that are used by several projects can use @code{DefaultValue}
+instead. Both functions work like @code{Value}, when the value isn't
+defined, but @code{SetValue} works like @code{to} if the value is
+defined, and @code{DefaultValue} doesn't set anything, if the value is
+defined.
+
+@example
+\ generic mach file for pc gforth                       03sep97jaw
+
+true DefaultValue NIL  \ relocating
+
+>ENVIRON
+
+true DefaultValue file          \ controls the presence of the
+                                \ file access wordset
+true DefaultValue OS            \ flag to indicate a operating system
+
+true DefaultValue prims         \ true: primitives are c-code
+
+true DefaultValue floating      \ floating point wordset is present
+
+true DefaultValue glocals       \ gforth locals are present
+                                \ will be loaded
+true DefaultValue dcomps        \ double number comparisons
+
+true DefaultValue hash          \ hashing primitives are loaded/present
+
+true DefaultValue xconds        \ used together with glocals,
+                                \ special conditionals supporting gforths'
+                                \ local variables
+true DefaultValue header        \ save a header information
+
+true DefaultValue backtrace     \ enables backtrace code
+
+false DefaultValue ec
+false DefaultValue crlf
+
+cell 2 = [IF] &32 [ELSE] &256 [THEN] KB DefaultValue kernel-size
+
+&16 KB          DefaultValue stack-size
+&15 KB &512 +   DefaultValue fstack-size
+&15 KB          DefaultValue rstack-size
+&14 KB &512 +   DefaultValue lstack-size
+@end example
+
 @node How the Cross Compiler Works, , Using the Cross Compiler, Cross Compiler
 @section How the Cross Compiler Works
 

machpc.fs

@@ -18,37 +18,37 @@
 \ along with this program; if not, write to the Free Software
 \ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
-true Constant NIL  \ relocating
+true DefaultValue NIL  \ relocating
 
 >ENVIRON
 
-true Constant file		\ controls the presence of the
+true DefaultValue file		\ controls the presence of the
 				\ file access wordset
-true Constant OS		\ flag to indicate a operating system
+true DefaultValue OS		\ flag to indicate a operating system
 
-true Constant prims		\ true: primitives are c-code
+true DefaultValue prims		\ true: primitives are c-code
 
-true Constant floating		\ floating point wordset is present
+true DefaultValue floating		\ floating point wordset is present
 
-true Constant glocals		\ gforth locals are present
+true DefaultValue glocals		\ gforth locals are present
 				\ will be loaded
-true Constant dcomps		\ double number comparisons
+true DefaultValue dcomps		\ double number comparisons
 
-true Constant hash		\ hashing primitives are loaded/present
+true DefaultValue hash		\ hashing primitives are loaded/present
 
-true Constant xconds		\ used together with glocals,
+true DefaultValue xconds		\ used together with glocals,
 				\ special conditionals supporting gforths'
 				\ local variables
-true Constant header		\ save a header information
+true DefaultValue header		\ save a header information
 
-true Constant backtrace		\ enables backtrace code
+true DefaultValue backtrace		\ enables backtrace code
 
-false Constant ec
-false Constant crlf
+false DefaultValue ec
+false DefaultValue crlf
 
-cell 2 = [IF] &32 [ELSE] &256 [THEN] KB Constant kernel-size
+cell 2 = [IF] &32 [ELSE] &256 [THEN] KB DefaultValue kernel-size
 
-&16 KB		Constant stack-size
-&15 KB &512 +	Constant fstack-size
-&15 KB		Constant rstack-size
-&14 KB &512 +	Constant lstack-size
+&16 KB		DefaultValue stack-size
+&15 KB &512 +	DefaultValue fstack-size
+&15 KB		DefaultValue rstack-size
+&14 KB &512 +	DefaultValue lstack-size