Chapter 11. P24 Metacompiler

Metacompiler is a term used by Forth programmers to describe the process of building a new Forth system on an existing Forth system. The new Forth system may run on the same platform as the old Forth system. It may be targeted to a new platform, or to a new CPU. The new Forth system may share a large portion of the Forth code with the old system, and hence the term metacompilation. In a sense, a metacompiler is very similar to a conventional cross assembler/compiler.

The P24 eForth metacompiler is contained in the source code file META24.F, which runs under Win32Forth, a public domain Forth for Windows 95/98/2000/NT. It calls on the following files to build the P24 eForth system:

ASM24.F P24 assembler

KERN24.F Kernel words in P24 eForth

EF24.F High level words in P24 eForth

K24.F Words to replace assembly macros

In this chapter, I take the source code in META24.F and explain the functions of the Forth words which build the eForth system.

11.1 Start Up the Metacompiler

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 META24.F loads all the source code and construct an image of P24 which can be ported to VHDL for Xilinx XCV300/1000E 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 on 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 hexadecimal. 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.

11.2 Tools of Metacompiler

VOCABUARY is a very powerful tool in Win32Forth. It initiate a new linked list of new words, which can be searched independent of existing vocabularies. The main vocabulary in Win32Forth is FORTH. The search order of the vocabularies can be specified by the commands ONLY and ALSO.

To compile the P24 system we reate two vocabularies. ASM24 will contain the words of the metacompiler, the assembler and all 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. They turn off the warnings normally supplied by Win32Forth on duplicated names and stack changes. These messages clutter the symbol table.

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

.HEAD prints teh name of a new word to be compiled.

CR is redefined so you can step through the compilation by setting debuggin? on.

-OR XOR. Chuck Moore preferred this name then XOR.

ONLY FORTH ALSO DEFINITIONS

HEX

WARNING OFF

' NOOP IS STACK-CHECK

variable debugging?

debugging? off

: .head ( addr -- addr )

>IN @ 20 word count type space >IN !

dup .

;

: 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 have the behavior of the original Forth words when you need them.

' ' 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

: -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.

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.

CREATE ram 8000 ALLOT

: RESET ram 8000 ERASE ; RESET

: RAM@ 4 * ram + @ ;

: RAM! 4 * ram + ! ;

: 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 ! ;

12.3 Write out a MIF File

The FPGA’s from Xilinx now contains large amount of block RAM’s which can be synthesized with core logic to produce large systems. The synthesis and FPGA programming tools supplied by Xilinx are in the Foundation 3.1I design suite. Foundation has a Core Generator which can produce RAM-ROM modules to be synthesized into the FPGA designs. The Core-Generator accepts RAM-ROM initial data from a MIF file, in which initial data to be programmed into the block RAM modules are stored in ASCII form. Each line contains one word in binary bit format.

WRITE-LOG-FILE is the command to dump the eForth memory image to a file named LOG.F, in the exact format required by the Core-Generator in Foundation. The contents of LOG.F can be copied into the MIF file for Core-Generator. Core-Generator will convert the MIF file into a .EDN file to be synthesis with the P24 VHDL core.

UBD. prints out a 24-bit number in 24 characters of 0’s and 1’s.

BDUMP dumps 2048 words of P24 image in the binary format.

: ubd. 0 <# $18 0 do # loop #> type cr ;

: bdump base @ binary cr

$800 0 do i ram@ ubd. loop

base ! ;

variable file-id

: write-log-file

s" log.f" r/w open-file

abort" create file error"

file-id !

base @ binary

800 0 do

i ram@ 0 <# 0d hold 18 0 do # loop #> file-id @ write-file

abort" write file error"

loop

base !

file-id @ close-file

abort" close file error"

;

11.4 Calling Other Building Blocks

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.

;; 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.

CREATE builds a new array word.

doVAR returns the array address.

VARIABLE builds a variable in P24 target.

: 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 ;

' EXIT alias ;;

\ ' WAIT alias ;; \ debugger

: CREATE makeHead begin .head CONSTANT doVAR DOES> forth@ call ;

: VARIABLE CREATE 0 #, ;

Now, we are 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 in the target P24 system have access to these functions.

CR

include k24

11.5 Boot Code

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@ #,

Now the P24 eForth is completely built in memory array RAM. You can inspect its contents using the commands:

0 SHOW

SHOW

SHOW

to dump 128 words at a time. Or,

SHOWRAM

to dump all the contents.

To dump the system in a form that will be acceptable to Xilinx’s Foundation 3.1I VHDL compiler, type:

BRAM

Copy the data thus displayed on the screen and paste them into the VHDL source code. You will then compile the P24 CPU core with the eForth OS code into FPGA, and can test the results on a actually Xilinx FPGA chip.