Commit 90dceb40 authored by pazsan's avatar pazsan

Started cross compiler documentation

Made 4stack, 8086, and MISC Gforth-EC work again
parent 3d3905a5
......@@ -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~
......
#!/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
......@@ -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
......
......@@ -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
......
......@@ -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
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment