Some notes on forthstrap

[Mark Cave-Ayland]

Hi folks,

With my attempt to figure out why the PPC builds aren't working, I've 
spent a little more time working on improving the error reporting in 
forthstrap. Having had more of an insight as to how forthstrap works, I 
figured it might be useful to share my notes on how the process works.

Tracing through the code, I now realise why my first attempt at locating 
errors didn't work very well. It seems that forthstrap 
(kernel/bootstrap.c) actually has two different modes depending upon 
whether a base dictionary is supplied on the command line or not.

- If no base dictionary is supplied, then the input source files are 
compiled using the C implementation of the forth interpreter realised by 
the interpret_source() function.

- If a base dictionary is supplied, load the base dictionary from disk 
and invoke the initialize word in order to run the forth kernel.

From the Makefile it is possible to see that the first time forthstrap 
is invoked, no base dictionary is supplied and so a dictionary 
containing a basic Forth interpreter is built using the C interpreter 
implementation in kernel/bootstrap.c.

On subsequent calls to forthstrap, the previous dictionary is passed in 
as a base dictionary. forthstrap loads the dictionary and invokes the 
initialize word to run the Forth interpreter. The important part is the 
#ifdef...#endif section in kernel/forth.c for the "key" word. What this 
does is override the default I/O functions so that the contents of each 
input file passed on the command line are piped into the kernel one 
character at a time.

By adding a new switch to forthstrap and trapping the "emit" word in a 
similar way, it is possible to redirect the console output to a separate 
file for debugging purposes. Hence I've added a -c switch to forthstrap 
and altered the build system so that for a given base dictionary 
foo.dict, a new file call foo.dict-console.log is automatically 
generated which shows the Forth words being piped into the kernel.

With these changes in place, the ability to debug a broken build is 
considerably increased. Now when I try and build one of the broken PPC 
builds (in this case pearpc), I get the following in SVN trunk:

Configuring OpenBIOS on amd64 for cross-ppc
Initializing build tree obj-ppc...ok.
Creating target Makefile...ok.
Creating config files...ok.
Building OpenBIOS for ppc
Building...error:
make[1]: Entering directory 
`/home/build/src/openbios/openbios-devel.pre/obj-ppc'
   GEN   target/include/openbios-version.h
   GEN   forth/version.fs
  HOSTCC host/kernel/bootstrap.o
  HOSTCC host/kernel/dict.o
  HOSTCC host/kernel/primitives.o
  HOSTCC host/kernel/stack.o
  HOSTCC forthstrap
   GEN   bootstrap.dict
   GEN   openbios.dict
   GEN   openbios-pearpc.dict
../arch/ppc/pearpc/tree.fs:64: no such device.
make[1]: *** [openbios-pearpc.dict] Error 1
make[1]: Leaving directory 
`/home/build/src/openbios/openbios-devel.pre/obj-ppc'
make: *** [build] Error 1

Surely enough, at the end of line 63 in arch/ppc/pearpc/tree.fs we see 
the following:

" /pci" find-device

Hence it seems as if no /pci node is being created which is breaking the 
pearpc build. And just to confirm this, the last few lines of 
openbios-pearpc.dict-console.log look like this:

build@zeno:~/src/openbios/openbios-devel.pre$ tail -n 5 
obj-ppc/openbios-pearpc.dict-console.log
0 >         h# 88201 encode-int " cpu-version" property  ok
0 >     0 encode-int " reg" property  ok
0 > finish-device  ok
0 >   ok
0 > " /pci" find-device

Now I've got things to the point where the error reporting works well, 
I'll get back to finishing up my loader consolidation patch...

ATB,

Mark.