/* file: inmos.doc               */
/* last modified: 19/03/98 13:39 */
/* by: alex stuebinger           */


G N U   O A K L I S P   F O R   T H E   T R A N S P U T E R
===========================================================


What has changed:
=================
A new t805 bootable is included.

The distributed binaries are now compiled with the /ta
switch.
"emulator.btl" is now configured for the t805.
If it doesn't run on your t4, please reconfigure it.

Good news for 1MB-users: I further reduced the amount of static data
the emulator needs.
The heap usage has been fine-tuned for 1MB systems.


Description:
============
This is a beta-release of version 1.00 of the Oaklisp Byte-Code
Emulator for the Inmos transputer.
WinNT/Win95 and DOS4G executables are included.
Also included is the latest source code for compiling it on unix
systems.

Barak Pearlmutter prepares a master release under the GNU General Public
License.

GNU Oaklisp is an object-oriented dialect of Scheme.

If you are new to Scheme you should read the book:

Abelson, Harold and Gerald Jay Sussman with Julie Sussman:
"Structure and Interpretation of Computer Programs.", 2nd ed., 1996.
The MIT Press, Cambridge, Massachusetts. ISBN 0-262-01153-0.

GNU Oaklisp was implemented by Barak Pearlmutter and Kevin Lang
in the late 80's.

Alex Stuebinger took the source code under a full revision and ported
it to standard ansi-c / posix, modularized it even further, introduced
some new features and eliminated some errors.

It is not parallel at the moment, as this is not easy to archieve on a
MIMD machine. It runs on any single transputer in any place of a network
with i/o access to the host.
We plan to implement a foreign function interface and channel communication
that it can communicate with other devices.
It then could be run on a controller tram communicating with a network.

The source code of the 1993 release lacking transputer support is on the
GNU Source Code CDROM, which is published by the Free Software
Foundation <gnu@prep.ai.mit.edu>.
It's also available via anonymous ftp from any GNU mirror
or by anonymous ftp from cs.cmu.edu in

	/afs/cs.cmu.edu/user/bap/ftpable/oaklisp/


The bootable worlds of Oaklisp are in the worlds directory.
The transputer needs the little-endian worlds, i.e. those ending in
".lo*".

Currently we distribute the old worlds of the 1993 edition, although they
need a patch to correct an i/o bug in the inmos toolkit, which causes
overwriting of previous output in the lisp-listener with the dos-version
of the inmos iserver. With the WinNT iserver all is fine.

The world "oaklisp.los" in this distribution has this patch not applied.

This distribution contains everything you need to assemble an unix
version. For sun you need the high endian worlds, they end in *.ol*.

You can prepare shell scripts for other operating systems than unix,
patterned after those of the 1993 release.
It's necessary to have a shell script for invoking the compiler.


You need:
=========
A TRAM with a 32-bit transputer, and at least 1MB RAM, although 2 to
4MB are recommended.

If you only have 1MB you can also build an Oaklisp world designed to your
needs (see below).

The t4 transputer suffices, because the Oaklisp code currently does not
use any floating point instructions.

It's only verified that it runs with iserver.

You may rebuild it, based on "emulator.lku."
For rebuilding the emulator from source you need the inmos ansi-c
toolkit or parts of this.


Files:
======
        emulator.lku    linked unit for /ta
        emulator.cfs    example configuration file for t805
        emulator.btl    iserver bootable file of bytecode emulator
                                /ta code
	emu805.lku      linked unit for /t805
        emu805.btl      iserver bootable file of bytecode emulator
                                /t805 code

        oaklisp.los     the oaklisp scheme world
        inmos.txt       this file
        copying         GNU General Public License
        fibo.oak        a sample oaklisp source code
        dos4gw.exe      tenberry's dos-extender
        emu_dos.exe     dos version of emulator
        emu_nt.exe      nt/win95 version of emulator
        lang.ps         Oaklisp language manual
        lim.ps          Oaklisp implementation manual
	/sources        the bytecode emulator sources
	/worlds         all worlds, *.lo* for little endian
				    *.ol* for big endian machines

How to start it:
================
Set any environment variables of your transputer development kit
correctly. Make sure the transputer cluster works.
You need the bytecode emulator which expects a bootable world on
the commandline.
Type
        iserver /sb emulator.btl oaklisp.los

And then you should get the listener.

Exit the listener properly with (exit).

If it doesn't work:


- and memory is the problem
  (e.g. caused by loading large files)
  (try a smaller lisp world or reconfigure it, see below, invoke with
   the -h switch, or build it completely new from source, see below)

- you may have the wrong transputer
  (recompile it from source, must have a 32-bit chip, see below)

- you may have the wrong configuration
  (e.g. you placed it onto a node, which cannot communicate with the
   host)
  (reconfigure it, see below)

- there maybe something wrong with the stack settings
  (reconfigure it, see below)

- it doesn't run under your server
  (see "tested systems", try do rebuild it)

- there might be a bug in it
  (read the source, report bug, see below).

- if it seems to not respond, it may be busy with a calculation
  (remember that the transputer is a slow 20 MIPS device)

- or try the WinNT/Win95 or DOS32 version to get a feeling.


If you should have several worlds, you can use wild-cards like
        iserver /sb emulator.btl oaklisp.++s
for the scheme world, or
        iserver /sb emulator.btl oaklisp.++c
for the normal oaklisp world, or
        iserver /sb emulator.btl oaklisp.++z
for the compiler world.

The machine automatically loads the world with the right endianity.

On Windows NT or Windows95 you start it with:
         emu_nt oaklisp.++s

You can prepare shell scripts to ease your typing.


For serious work:
=================
Type your source code in emacs in Scheme mode (file-extension ".oak");
then save your work, invoke Oaklisp, and then type
(load "sth.oak") to the listener prompt.

You may dump a new warm world on exit with the switches
        iserver /b emulator.btl -d -b -G oaklisp.++s
you will then be prompted for the filename of the new world.

It is generally recommended to compile files and dump new worlds
on WinNT/Win95, DOS32, linux or unix as the transputers are relatively
slow.
E.g. the t805/20MHz takes about 70 times as long as an PentiumII/300MHz
doing lisp.

You can reserve more memory for the lisp-world by giving the switch
 -h [bytes], e.g.
        iserver /sb emulator.btl -h 1024k oaklisp.los

Of course you have to reconfigure the heap of emulator.btl before doing
that, to avoid an "out of memory" message.
This is also of importance for using the byte-code compiler.

You can suppress all garbage collector related output giving the -Q
switch.

For more switches consult the manual.


Tested systems:
===============

Alex <stuebi@mail.uni-mainz.de> has tested:
===========================================
On a T805-20MHz 16MB TRAM configured as root.
It sticks on a inmos b008 running iserver with Windows NT as the host
operating system.
(fibo 26) takes 74.60 secs on the t805-20 under 1MB.
The distributed binaries were used.
The PentiumII/300Mhz takes 0.99 secs for that.


Please mail reports with your results to me (Alex).
I will then include your configuration in this section.
I also will report you email address, so that other users can profit
from your experience, if they have a similar configuration.
Please tell me, if you want your email-address not included.
As the transputer users are a small community this seems to work.


Some benchmarks:
================

(fibo 34) on a Gateway PentiumII/300Mhz
---------------------------------------------------------------------------
Gold-Hill Common Lisp for NT 5.0 | Native Code Compiler   4.45 secs
                                 | Interpreter          196.72 secs
---------------------------------------------------------------------------
Oaklisp ver. 1.00 of emu_dos     | Interpreter           47.45 secs
---------------------------------------------------------------------------
MIT-Scheme 7.4 for linux         | Native Code Compiler  10.50 secs
                                 | Interpreter           75.00 secs
---------------------------------------------------------------------------
Watcom C/C++ 32, 9.5 win nt      | C Compiler             1.16 secs
---------------------------------------------------------------------------

(fibo 34) on an inmos t805-20MHz 1MB, 3 wait states, ta code
---------------------------------------------------------------------------
Inmos CC 3.01.41                 | C Compiler            30.207 secs
---------------------------------------------------------------------------
The t805-20 is 26 times as slow as the pentium 2 with C-code.


(fibo 26) on an inmos t805-20MHz 1MB, 3 wait states, ta code
---------------------------------------------------------------------------
Oaklisp ver. 1.00 of emulator    | Interpreter           74.60 secs
---------------------------------------------------------------------------
Inmos CC 3.01.41                 | C Compiler             0.643 secs
---------------------------------------------------------------------------

(fibo 26) on an inmos t805-20MHz 1MB, 3 wait states, t805 code
---------------------------------------------------------------------------
Oaklisp ver. 1.00 of emulator    | Interpreter           74.08 secs
---------------------------------------------------------------------------
Inmos CC 3.01.42                 | C Compiler             0.643 secs
---------------------------------------------------------------------------

(fibo 26) on an inmos t400-20MHz 1MB, 3 wait states, ta code
---------------------------------------------------------------------------
Oaklisp ver. 1.00 of emulator    | Interpreter           80.06 secs
---------------------------------------------------------------------------
Inmos CC 3.01.41                 | C Compiler             0.866 secs
---------------------------------------------------------------------------



What you should know prior to rebuilding or reconfiguring it:
=============================================================
The distributed "emulator.btl" is configured for the t805.

I squeezed it under 1MB, to run on the most modest modules.
But this is driving the garbage collector crazy, because
the Scheme world "oaklisp.los" is a large one.

For systems with only 1MB #define MAX_NEW_SPACE_SIZE.
#define STACK_BUFFER_SIZE (8*1024) as well.

If you only have 1 MB you can even try to build yourself a
reduced world from the lisp-source, which can consist of that
parts of the language you actually use in your application (caution!).
It's recommended to build the new worlds under unix because of
the long filenames and of the makefiles.

To get something really working you better have 2 to 4 MB.
Invoke the emulator with the -h switch after reconfiguring the heap.

You can recompile the byte-code emulator to get the full speed out of
your t805 for example.

You need the inmos ansi-c toolkit or parts thereof.
The new ansi-c revisioned source code for the byte code emulator is
in the /source directory.

Read carefully "config.h".
For inmos you must compile with the /fs switch to get arithmetic
right shifts.
You can make a fast version if you #define FAST; give it to the
compiler with /dFAST.
Doing so, you do not need to link "instrs.tco" as this is not
needed.

Forget about the warnings the inmos compiler emits for "emulator.c".
ICC is particularly pedantic.
We might state the code clearer at an later stage.

For linking, you should know that the i/o -extended run-time libraries
must be used, as the lisp needs file-i/o and does messageing to the
console.

It's not tested in a reduced environment (i.e. without a host), which
you need for burning it into ROM.
Does LISP make sense in such a configuration?

You should work out correctly the heap settings for your given
transputer module, please change DEFAULT_NEW_SPACE_SIZE accordingly.

You may have to experiment to find the optimal combination for your module.
Use the largest heap you can get in "emulator.cfs" for your transputer module.
Choose a setting, so that the collector complains, it cannot get the
code into. It will give information about the size it requires.
Then gradually decrease the heap by 1k steps until the tools
stop complaining.
Or calculate the maximum size out of the memory mapping information.
Squeeze every byte out of it. Lisp is a big application.

If you get an "out of memory" message, decreasing the
DEFAULT_NEW_SPACE_SIZE  may help.

It isn't exactly recommended that you experiment with the stack
settings.
Only if you are feeling adventurous try a smaller stack size,
please compile with the /ks option to enable stack checks.
This may slow down performance but it is a good test.
In my tests a stack size of 2k sufficed.
This is optimal with the 2kB internal SRAM on t400 transputers.

The released binaries are compiled for ta (all 32-bit transputers).
I also compiled it without /ks for optimal performance.
If it should hang for unknown reason during a power-demanding application,
increasing the stack size may help.


What is planned:
================
Floating point support.
So far Oaklisp knows nothing about channels, planned are
Communicating Sequential Processes Extensions.
You may participate in these efforts!
Mail any modifications to us.


Known problems of the transputer version:
=========================================
User break with Ctrl-C or Ctrl-Break aborts the iserver but should only
interrupt lisp computation.
This seems to be a problem with iserver.
iserver should pass the signal to the application rather than intercept
it.
iserver should be recompiled from the inmos sources to take this into
account.
It's unlikely that we do this work.

The listener overwrites previous output while printing to the console
running on the dos version of the inmos iserver.
The new worlds which are to be released soon are correcting this bug.


When you make bug reports:
==========================
Address transputer related problems only to:
Alexander Stuebinger, <stuebi@mail.uni-mainz.de>
Barak has no transputer.

Please include information about your tram.
Please note, that I don't know much about the cryptic abbreviations,
which inmos used to denote its tram parts (like "IMS-B414-14A", etc.)

But I know something about inmos processor types.
What is important to me is the processor type, the clock frequency,
and the amount of ram installed.
As well as the server which communicates with the board, whether it is
"iserver" or "afserver".
And the host operating system, e.g. whether it's solaris or win95 or dos.
Please include information about your card and the manufacturer.

When reporting benchmarks it's also necessary to give the RAM-type
(whether it's DRAM or SRAM) the amount of internal RAM, and the
wait-states.


Please report buggy behaviour and address any suggestions to:
=============================================================
(Transputer version and all other opsys:)
Alexander Stuebinger, <stuebi@mail.uni-mainz.de>

(Other opsys, lisp implementation semantics:)
Barak Pearlmutter, <bap@cs.unm.edu>
Homepage: <http://www.cs.unm.edu/~bap>
