OPERATING SYSTEM
================

I've built ismene on Linux redhat 5.1 and 5.2.
I suspect it should work fine on suse and slakware
but have not actually done this. In theory it should not
be difficult to use the "hacked" p2c translater inside the
m2f package to translate ismene into C, which would greatly open
up the porting possibities.

Please feel free to improve the installation or anything
for that matter.
All help/suggestions will be gratefully received.


INSTALLATION
============


Note that to build ISMENE you will need:

(i)   lesstif   ( ./configure ; make all ; make install)
(ii)  binutils with is32 architecture to be installed on your machine.
(iii) m2f (3.5) (modula-2 compiler)

[ all three can be found on floppsie.comp.glam.ac.uk via ftp in pub/m2 ]

m2f (3.5) can be found on tsx-11 and mirrors (also redhat.com for rpm/srpm)
lesstif (can be found on the hungary programmers web site. www.hungary.com ?)
is32-binutils and is32-gdb are currently located on floppsie.comp.glam.ac.uk.

Firstly install the Modula-2 compiler (m2f) and ensure that your path
is set to find the compiler. (it maybe located in /usr/local/bin).

Secondly install lesstif (I used 0.85 which is rather old now)
I installed it in /usr/local/lib /usr/local/include etc

Thirdly unpack ismene and binutils/gdb

      ie:

      gzip -d -c ismene.tar.gz | tar xvf -
      gzip -d -c is32-binutils-2.9.1.0.4.tar.gz | tar xvf -
      gzip -d -c is32-gdb-4.17.tar.gz | tar xvf -

#     and configure them:

      ( cd is32-binutils-2.9.1.0.4 ; sh -x ../m2/ismene/to-make-is32-bin )
      ( cd is32-gdb-4.17 ; sh -x ../m2/ismene/to-make-is32-gdb )

#     now compile binutils and gdb

      ( cd is32-binutils-2.9.1.0.4 ; make )
      ( cd is32-gdb-4.17 ; make )

#     and install gdb/binutils
#
#     after we have installed the tools below we should have
#     as-is32, nm-is32, ld-is32 ... and the binutil libraries (is32)
#     and also gdb-is32

      su
      ( cd is32-binutils-2.9.1.0.4 ; make install )
      ( cd is32-gdb-4.17 ; make install )
      exit

#     now compile ismene

      ( cd m2 ; make ismene )

#     and install ismene

      su
      ( cd m2/ismene ; make install )
      exit

#     you now need to set your LD_LIBRARY_PATH so that it can see
#     the lesstif libraries  (should be in /usr/local/lib)
#     in which case:  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
#     for bash users

#     now ismene should be ready to run


SIMPLE TEST OF ISMENE
=====================

#     now perform Hello world test

      cd m2/os/rtp/ass1
      make sim
      cd sim
      ismene
      cont                    # when ismene waits for input

# hopefully you will see:

Time   : 0.0000000000000 seconds, internal time=0
Machine:    1
Port   :    0
PC     :    0
Process: init
Reason : user interrupt


cont
hello world
ass1.mod:19:the end
Ending Simulation
***************************************************
* Entering Monitor                  In Simulation *
***************************************************

../ass1.out:Debug_Halt:~21:
Time   : 0.0000150450000 seconds, internal time=150450
Machine:    1
Port   :    0
PC     :  721
Process: init
Reason : user interrupt

-- end of test --


ISMENE REGRESSION TESTS
=======================

( cd m2/ismene ; make simtest )

and go and have a long coffee.


ISMENE RUNTIME OPTIONS
======================

To get a graphical representation of the run time of the microkernel
use -X option.

To debug with gdb run ismene with -gdb option. If you do this you
will need to use gdb-is32 (see above) and need to create a .gdbinit
see example inside os/rtp/ass1/sim/.gdbinit
Basically the target field must be altered to your machine name
and the socket number needs to match the socket number displayed
by ismene. By default this is 8000 but it will choose the next
available one if 8000 is in use.


TO DO
=====

+ documentation in particular file formats and is32 processor manual.
+ device modelling and multiprocessor capability needs overhauling.

Any problems, please email me: gaius@glam.ac.uk
