        os9l1: An OS9 level I emulator that runs under UNIX/Linux
------------------------------------------------------------------------------

Ambition level:
~~~~~~~~~~~~~~~
To be able to run OS9 level I programs without the OS9 kernel. More
specifically: to be able to run BASIC09, C-compiler, Pascal-compiler and
the assembler so it is possible to write programs that is executed on a
"raw" 6809 emulator with the full os9 kernel installed. This implies
that a lot of other simple programs will also work, but not the following:

How far have I come? Well, Pascal-compilation to P-code works. But the
P-code interpreter loads an extra module and os9l1 doesn't handle that,
so execution of your P-code is not available. Then you could compile
to native code, but the native code compiler is in P-code itself, so ...

In addition, the C.PREP complains about "grab overlap" when it sees
the statement #include <stdio.h>. I have not found the cause of that.

Other programs that don't work:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
pxd, pwd: These open the current directory, read the first two
 entries and then do a getstat opcode 14. Since they expect the
 directory to be in os9 format I can only be partially successful.

dir: Opens the directory, and expects it to be in the os9 format.

procs: Accesses memory directly at a given address to get the running
 processes, rather than go through a system call.

mdir: Accesses memory directly at a given address to get the loaded
 modules, rather than go through a system call.

attr: Attr will first open the file, then do a getstat with
 opcode 0, to get the information stored in the buffer at position
 $1C-$1F, Then open the filename '@' and make a seek. The file '@'
 is a "secret" name for the entire harddisk.

tmode: Apparently it calls a routine it finds out about when it 
 does a getstat with opcode 0. Since that part of the buffer is
 zeroed, tmode crashes with illegal 6809 instruction.

I don't know if this software is useful to anyone, as I don't know if
the 6809 is used by anyone anymore for even traffic lights, but since
the kernel module is pretty isolated, it might be possible to replace
the 6809 emulation with an emulator for a more modern processor and
thereby make it possible to make an emulator for newer OS9 versions on
any UNIX-like system.

Installation
~~~~~~~~~~~~
The tarball contains three emulators; Usim, which is Ray's original
emulator, os9l1 to emulate os9 and v6809 which is an attempt to emulate
a 6809 computer with "ideal" devices. The v6809 does not work yet.

Once you have unpacked the tarball, type 'make'. 

But before you do, you might want to modify the os9::loadrcfile() function
in the os9krnl.cc file. Until I have implemented a configuration file
this is where you make modifications. Also check os9::os9().

If you have made no modifications, os9l1 expects you to have the
OS9 software and supporting files in the OS9 directory in your home
directory. So in your home directory do:

mkdir OS9
mkdir OS9/CMDS

Then copy your OS9 programs to OS9/CMDS. Start with 'shell'. In the CMDS
directory in this package you will find some freeware software you can
use. One is the 'ar' program, so you can unpack files downloaded from
the os9archive. Another is the 'ed' editor, as known from UNIX.

Once you have compiled os9l1 by running make, you can run it. If you give
it no arguments, it will run 'shell'. Your current data directory will
be the same as your current UNIX directory, and your current execution
directory will be $HOME/OS9/CMDS.

NOTICE: OS9L1 DOES NOT CONVERT UNIX LINEFEEDS TO OS9 CARRIAGE RETURNS
AND VICE VERSA FOR TEXT FILES.

On Linux you can configure the kernel to run OS-9 programs as if they
were native to Linux. First copy os9l1 to /usr/local/bin/os9l1. Then
copy binfmt/os9 to /etc/init.d/os9. On Redhat do as root:

chkconfig os9 --add
service os9 start

Other Linux systems may be different. The script tells Linux to call
os9l1 on files that has 0x87CD as the first two bytes. Now simply add
$HOME/OS9/CMDS to your $PATH.

Compiling from checked out sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
svn co http://svn.roug.org/repositories/osnine/trunk osnine
cd osnine
autoreconf
./configure
make

To run the unit tests, type: make check

Installation and configuration of v6809
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
v6809 is an attempt to make an emulator, which uses the original OS9
kernel. But instead of emulating the keyboard and disk controller
verbatim, I create simple hardware simulations. These typically
trigger on a specific memory location like 0xFF40. Since the emulator
knows the content of the registers it can simply get that character
from the keyboard and put it at the address pointed to by register X -
whatever.

The source for the new devices drivers are in the devices directory.
A make in this directory will produce a rom.s1 file, which you give as
argument to the v6809 program. However, at the time of this release
it didn't work.

Further development of the operating system interface will be difficult
though.  Level I takes some shortcuts and in some programs, as far as
I can determine, grabs bytes from wellknown locations. In addition,
user-programs are allowed to directly execute system modules, whose
addresses are handed to them through the i_getsst call. The conclusion
is that it will be a better approach to emulate just the hardware, and
then let the Microware OS9 kernel run inside it. Even better would be
to define some "idealized" hardware that is easy to write an OS9 device
driver for and is easy to emulate.

Most of the stuff you see here is Bellis'. My os9-emulation is located in
the file os9krnl.cc and os9l1.cc. I've also made a few changes and fixes
to Bellis's files. For example the ability to load Motorola S-Records.

November 2011,
Soren Roug <soren@roug.org>
Havneholmen 74, 6. th
1561 Copenhagen V
Denmark

------------------------------------------------------------------------------
        THIS PART IS THE ORIGINAL README FILE FROM RAY BELLIS
------------------------------------------------------------------------------

~~~~~~~~~~~~~~~~~~~~~~~~~~~
usim-0.91: mc6809 simulator
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is a Motorola mc6809 simulator written in C++.   

The processor simulator is implemented as a C++ class and it is
designed to be subclassed to provide virtual I/O devices and status
information.

The `mc6809' class doesn't provide any status information, but the
derived `mc6809_X' class shows processor status in an X Window.

The simple `sys' class in main.cc adds a virtual mc6850 UART by
overloading the `read' and `write' methods.

The previously released version (0.1x) had some serious bugs in the
instruction decoder but this latest version seems to run perfectly.
It successfully runs the Tiny Basic interpreter that was posted
to comp.sys.m6809 a few months ago.

v0.91 adds rudimentary support for running under DOS.  To be more
useful a minimal `conio' based terminal emulator needs to be built
into the DOS terminal handling code.

------------------------------------------------------------------------------
R. P. Bellis				E-Mail:	<Ray.Bellis@psy.ox.ac.uk>
Computing Officer
MRC Centre in Brain and Behaviour
Dept. of Experimental Psychology
University of Oxford
South Parks Road			Tel:	+44 865 271359
Oxford OX1 3UD				Fax:	+44 865 310447
------------------------------------------------------------------------------
