        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.

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.

How it all started
~~~~~~~~~~~~~~~~~~
It all started, when my parents told me, that they were looking for
a smaller home, and that there would be no room anymore for some of
the things that I had stored with them. One of those things was my old
Dragon 64 with floppy drive and floppy disks that I haven't used since
the late eighties.

Having noticed I still had this computer in good condition and remembering
how much time I used to spend with it, I put it all together and turned
it on.  Distressingly, but unsurprisingly I could not read a single of
the floppy disks.

As a teenager I had purchased OS9. I found it quite confusing in the
beginning and less efficient than DragonDos, but soon began to appreciate
its flexibility.  So when I later saw UNIX at the technical school,
where I took my computer science degree, I said to myself - oh, it's just
like OS9, I already know this stuff. That was a defining moment for me,
I specialized in UNIX because of OS9.  Having big iron available I lost
interest in OS9 before I had exhausted my curiosity for its design -
presuming I could always go back and revisit it when I had the desire.

What do you do when you have unreadable floppy disks? I strapped a 5.25"
inch drive to my PC, and used Paul Burgin's VCOPY program to see if I
could read the disks. I could, but with 30 - 40% errors. Reading the same
disk 10 times and the merge the result lowers this to 20 - 30%. Since
many of the files were stored on more than one floppy disk I could use
a binary editor to take blocks from here and there, and reconstruct
each program. It became easier when I developed tools to do it, and
I reverse engineered the 'ident' program - including the CRC-check to
verify the reconstruction of the commands. I managed to reconstruct a
significant amount, but there were several which eluded me. E.g dcheck,
dsave, format, most of the C-compiler programs except for c.asm and cc1.
Mm from stylo. Almost everything from Pascal, and I only had dynacalc on
one single disk, and I could not read the first sector with the $87cd,
so I don't know where on the disk dynacalc is hiding.

I shiver when I think about how many hours I spent that winter with a
hexeditor. Later the next Spring I found an old 386SX. I installed the
5.25" floppy drive, and wouldn't you know it; All the "faulty" disks
were readable without problems!

One problem I had/have is that I must boot into MS-Windows to run the
Dragon emulator. I use Jon Smith's PC-Share. The whole idea of this
exercise is to archive my old Dragon and still be able to play
with the software in an emulator in 10 - 20 years. And frankly, in
10 years - Microsoft will still be there, but the Windows API is too
hardware dependent on 80x86 to be supported in 20 years in its current
form. The only API with a proven longevity is the UNIX system call
interface - POSIX. UNIX is almost 30 years old, and you can still
compile the software of those days with very small modifications.

I found Alan DeKok's ocem, but quickly found that it was an abandoned
project. It would only run very simple OS9 applications. It seemed
possible though, that with a little effort I would be able to implement
the missing functionality. I decided to base my work in Ray Bellis'
6809 emulator, as it was very "clean", and could easily be subclassed.
There were bugs in Bellis's emulator, but I squashed them by comparing
functionality with DeKok's emulator, and then try to figure out which
one did it correctly.

I quickly copied DeKok's os9 system calls to my own product and continued
from there. I now have implemented almost all Level I system calls. The
rest are only used in very specific situations. And I got to learn the
internals of OS9 and C++ programming at the same time!

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.

September 2001,
Soren Roug <soren@roug.org>
Vagtelvej 59, 3. tv.
2000 Frederiksberg
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
------------------------------------------------------------------------------
