( Copyrighted by eMAST Technology Corp, 2000 )
( All rights reserved )

comment:
meta24.f  07nov00cht, change for P24, p24c
          02dec00cht, interpreter ok, debugging compiler

This meta-compiler was originally written by Chuck Moore to build
Forth systems for the MuP21 microprocessor.  It can be easily
changed and used to compile code for any CPU.

This file loads all the source code and construct an image of P24
which can be ported to VHDL for Xilinx XCV300/1000 FPGA.  It runs
under Win32Forth, a public domain Forth system authored by Andrew
McKewan and Tom Zimmer.  It can be downloaded from the web, at
www.forth.org, under the category of Compiler/Windows.  Click on
the download button, and it will be downloaded to your computer
and automatically installed.

Run Win32Forth from your desktop, or from Start/Program/Win32Forth and
you will see a window opened.  Open the WinView editor from the File
menu.  Open the file META24.F through the directory tree.  Then
click back the Win32Forth window and type:
        fload meta24
Youu will see the list of all the words compiled into the P24
target image.  Type
        showram
to show the image dumped out in hexidecimal.  Type
        bram
to see the image dumped in a form acceptable by Xilinx VHDL.  Cut
and paste this image into your VHDL code and synthesize the P24
system.

In this file, I take the source code in META24.F and comment on
all the words so you will understand them and perhaps improve on
them.  You can adapte them to your own CPU if so desired.

comment;

\ create two vocabularies. ASM24 will contain the assembler woprds
\ and the words in the P24 target.  SIM24 will contain words which
\ build a cycle-based simulator to exercise code in the P24 target.

VOCABULARY ASM24
VOCABULARY SIM24

\ following are tools words added to the baseline Forth system
ONLY FORTH ALSO DEFINITIONS

\ turn off the warnings normally supplied by Win32Forth on
\ duplicated names and stack changes.  They clutter the symbol
\ table.
HEX
WARNING OFF
' NOOP IS STACK-CHECK

\ type 'debugging? on' and you can pace the meta-compiler by
\ hitting SPACE for the next steps.  Hit RET to stop.
\ This is useful when you want to locate errors before a full
\ compilation.
variable debugging?
debugging? off

\ .HEAD prints teh name of a new word to be compiled.
: .head ( addr -- addr )
   >IN @ 20 word count type space >IN !
   dup .
   ;

\ CR is redefined so you can step through the compilation by
\ setting debuggin? on.
: CR CR
   debugging? @
   if .s KEY 0D = abort" done"
   then
   ;

\ Here is a group of Forth words which clash with words in the
\ target.  You can use the aliases to ensure that you still
\ has the behavior of the original Forth words.
' '      alias forth'
' dup    alias forthDUP
' drop   alias forthDROP
' over   alias forthOVER
' swap   alias forthSWAP
' @      alias forth@
' !      alias forth!
' and    alias forthAND
' +      alias forth+
' -      alias forth-
' word   alias forthWORD
' CR     alias CRR
' .(     alias forth.(
' count  alias forthCOUNT

\ Chuck Moore preferred this name for XOR.
: -OR   XOR ;

\ RAM is a large array to hold the binary image of P24 target.
\ P24 is a 24-bit CPU.  One 24 bit program word is compiled into
\ a 32-bit word in this array.
\ RESET clears the RAM array.
\ RAM@ ( a ) uses a word address to fetch a program word in RAM.
\ RAM! ( n a ) stores a word n into RAM at address a.
CREATE ram  8000 ALLOT
: RESET   ram 8000 ERASE ;   RESET
: RAM@   4 * ram +  @ ;
: RAM!   4 * ram +  ! ;

\ FOUR displays four consecutive words in target.
\ SHOW displays 128 words in target from address a.  It also returns
\ a+128 so you can SHOW the next block of 128 words.
\ SHOWRAM displays the entire image, 2048 words.
: FOUR   4 0 DO  DUP RAM@ 7 U.R  1+ LOOP ;
: SHOW ( a)   10 0 DO  CR  DUP 7 .R SPACE
      FOUR SPACE FOUR  LOOP ;
: showram 0 0c 0 do show loop drop ;

\ UD. displays a 24-bit word in 8 digits with leading zeros.
\ B. displays one byte in two digits.
\ C. displays nibble in one digit.

\ STRING. displays the attribute init string in the VHDL format
\ required by Xilinx Foundation synthesizer.  The string
\ "attribute INIT_" is temporarily replaced by "qq" to avoid
\ lines broken by Forth output routine.  When the whole
\ attribute blocks are pasted into the VHDL code, "qq" must
\ be globally replaced by "attribute INIT_".

\ EIGHT displays one line of memory attribute for VHDL
\ BLOCKRAM displays one block of memory attributes for VHDL
\ BRAM dumps the entire memory blocks for VHDL
: ud. 0 <# # # # # # # # # #> type ;
: b.  0 <# # # #> type ;
: c.  0 <# # #> type ;
: string. ( a ) 8 / 10 /mod swap
\        ." attribute INIT_" b.
        ."  qq" b.
        ."  of memory" 0F and c.
        ." :label is " 22 emit ;
: eight   8 + dup 8 0 DO  1 - DUP RAM@ ud.  LOOP DROP ;
: blockram ( a)   10 0 DO  CR DUP string.
      eight 22 emit 3B emit LOOP cr ;
: BRAM base @ hex 0 0F 0 do blockram loop drop base ! ;

\ Now we compile the structured, optimizing assembler for P24.
CR .( include asm24 )
include ok24

\ Now we compile the kernel portion of the P24 eForth system.
$18 org
CR .( include eforth kernel )
include kern24

\ This set of words will be used to build high level control
\ structures in the body of eForth system:
\       BEGIN ... AGAIN
\       FOR ... NEXT
\       FOR AFT ... THEN NEXT
\ LIT let LDI to assemble a literal
\ $LIT compiles a counted ASCII string, packed three bytes to
\ a 24-bit program word.
: again ( a -- )
   jump ;
: for ( -- a )
   push begin ;
: next ( a -- )
   doNEXT jump ;
: <next> next ;
: aft ( a -- a' a" )
   forthDROP begin 0 jump begin forthSWAP ;
: LIT ( d -- )
   ldi ;
: $LIT ( -- )
   22 forthWORD forthCOUNT
   forthDUP ,B ( compile count )
   0 DO
      forthCOUNT ,B ( compile characters )
   LOOP
   forthDROP ;

\ ;; terminates a high level colon word with a ret.
\ WAIT pauses the execution.  Restart by any key.  This is
\ a cheap breakpoint mechanism, now replaced by the simulator.
' EXIT alias ;;
\ ' WAIT alias ;;               \ debugger

\ CREATE builds a new array word.  doVAR returns the array address.
\ VARIABLE builds a variable in P24 target.
: CREATE makeHead begin .head CONSTANT doVAR DOES> forth@ call ;
: VARIABLE CREATE 0 #, ;

\ Ready to compile the high level portion of the P24 eForth.
CR .( include eforth24 )
include ef24

\ Compile Forth words used as macros in assembler, but now needed
\ so the Forth interpreter and compiler have access to these
\ functions.
CR
include k24

CR

\ Build the boot code starting at location 0.  This piece of code
\ initializes the variables in RAM memory and then jumps to COLD.
0 ORG
10 LIT 704 LIT 6 LIT
forth' COLD >body forth@ LIT
push push
anew H forth@
   push sta ldp push
   lda pop pop sta
   stp lda
<next>
pops pops ret

\ Build the table of initial values for the variables to be
\ copied to RAM memory on booting.
10 ORG
730 #,
0A #,
lastH forth@ #,
780 #,
lastH forth@ #,
forth' $INTERPRET >body forth@ #,
forth' QUIT >body forth@ #,


