Beta Release Notes for the Macintosh Port of F68KANS (11/95)

This F68KANS port to the Macintosh was done by rewriting the
ATARI loader and compiling it with THINK C. In its current form 
this port has two problems explained below. 

Apart from that it has NO Macintosh specific support such as 
access to the Macintosh Toolbox. To have this, it might be wise to
use a 'native' Mac Forth, such as Yerk or Mops.

On the other hand F68KANS runs with the SAME image exactly as 
it does on a 68K based micro controller, so this Mac port can 
be used to ease development for such an embedded F68KANS.

Please consider this release as a beta release.
It is made public in hope more experienced Mac programmers
will look at the port, remove the problems it has, and improve it.

Please give feedback.

Thanks to Joerg for developing F68KANS.

If you have any comments or suggestions I would be happy
to accept them: Please send me an email:
           
                         uho@pizzicato.forth-ev.de


Overview
--------

F68KANS is quite easy to port between different 68K platforms.
For the Macintosh, three main things were done:

1) The C-based loader written for the Atari was modified to
    satisfy both Macintosh requirements in general as well as
    specific THINK C requirements. This covers different path
    names, support for console I/O. Compare the Atari loader 
    to the Mac loader for details. 

2) Since F68KANS uses A5 in its virtual machine implementation,
    and MacOS uses this register for adressing some kinds of 
    memory segments, there is a slight incompatibility between 
    the Mac and F68KANS. Major parts of the functions in BIOS.C 
    and CLIB.C were modified to set A5 correctly. 
    The THINK C provided C function SetCurrentA5(); does this.

3)  The functions defined in BIOS.C CLIB.C and FLOAT.C 
     were limited to those provided by THINK C. The related files
     BIOS.SI CLIB.SI and FLOAT.SI were changed accordingly.
 


Generating a full F68KANS image
------------------------------
The File "F68KANS Project" is a THINK C project file, which
declares the files necessary to build the loader. These are
LOADER.C BIOS.C CLIB.C FLOAT.C as well the ANSI and unix 
libraries. 
The loader can be built in two different versions:

1) A version which displays an entry screen and allows to
    input a command line with parameters.
    This version is precompiled in "F68KANS with parameters"

2) A version which directly starts loading the default
    configuration file (F68KANS-Configuration) and thus
    effectively boots the default full F68KANS image 
    ("F68KANS-Image") without asking any questions.
    This version is precompiled in the file F68KANS.

A new option has been added to the version 1). 
It is the -b option for booting the whole system.
This uses the F68KANS.CFG configuration file and thus loads the
F68KANS image in file F68KANS.IMG. 
It will then load all files mentioned in STREAM.IN, writing the
resulting image to "F68KANS-Image". 
This full image can be started with version 2) of the loader.
 
Forth source code which has to be modified for the Mac -
mostly to reflect the changes in the loader - can be found
in INITSI.4 BIOS.SI CLIB.SI FLOAT.SI and finish.4.
The new file postlude.4 was added to have a dedicated place
for user extensions. 

PROBLEMS
---------

Since I'm in no way an expert in Macintosh programming, the
port in its current status has two major drawbacks, which I am
not able to resolve on my own:

1) The Floating Point Support crashes the system immediately.
    I could not detect any mistakes in FLOAT.C and the related file
    FLOAT.SI. I traced the appropriate Functions in FLOAT.C and
    it appears to me that crashing takes place somewhere in 
    the SANE-firmware. I feel unsatisfied with this, and it
    detracted me from preparing an earlier release. I now have
    decided to build a version without float support. The source 
    code I used is still supplied in the hope, a Macinstosh/SANE-
    expert will take over and resolve this mystery.

2) The F68KANS window sometimes does not refresh.
    This looks like F68KANS misses the refresh event (which
    I assume must exist in MacOS) from time to time. Pure C
    programs which as well use THINK C console support do not
    show this effect, although they execute similar code. Anyway -
    a refresh of the F68KANS window can be forced by clicking the
    zoom field  in the border (upper right corner). Again I hope a
    Mac/THINK C expert can help.


Ulrich Hoffmann, November 1995