readme

Welcome to PMOS. PMOS is a set of modules, mostly written in Modula-2, to support multitasking. PMO

README file for the PMOS multitasking software
==============================================

Welcome to PMOS.  PMOS is a set of modules, mostly written in Modula-2,
to support multitasking.  PMOS was designed primarily with real-time
applications in mind.  It is not an operating system in the conventional
sense; rather, it is a collection of modules which you can import
into your own programs, and which in particular allow you to write
multi-threaded programs.

Even if you don't need multi-threaded programs, you might find some
of the general-purpose modules useful.

Subject to certain conditions which are described below, this
software is free.

The notes in this file show you how to install PMOS and how to get
started.  More detailed information may be found in a report called
"The PMOS Definition Modules", which can probably be found at the
same site where you obtained this software.  (If not, contact the
author - see contact information below.)  The current edition of that
report is slightly out of date (a new edition is planned but not
yet available), but discrepancies are easily resolved by looking at
the definition modules.  Since complete source files are included
with this distribution, experienced programmers may well find
that the additional documentation is redundant.


DISCLAIMER

Like all free software, this package is supplied "as is", and no
warranties are made or implied as to its fitness for any particular
purpose.  The author does not accept responsibility for any damage,
including consequential damage, caused by the use of this software,
except to the extent to which this disclaimer may be overridden by law.


LICENCE INFORMATION

The ACCOUNTS directory of this package contains a shareware product.
Licence information for that product is given in a separate README
file in the ACCOUNTS directory.  You may, if you wish, delete the
contents of the ACCOUNTS directory and its subdirectories without
affecting the functionality of the PMOS package.

All of the remaining components of the PMOS package may freely be
used subject to the following conditions.  If you do not accept the
conditions, do not use the package.  Your use of any part of PMOS
implies your acceptance of these conditions.

1. Neither PMOS nor any derived product may be sold or distributed
   for a fee, or used to enhance the value of a product for which a
   fee is charged.  The author is willing to negotiate agreements with
   individuals or companies for commercial use of PMOS, but in the
   absence of such an agreement PMOS is for non-profit use only.

2. You may give copies of PMOS to other people, but only if this
   README file is included.

3. You may modify PMOS, but only if you agree that the altered
   version continues to be subject to the conditions given here.
   The name of the original author, and any copyright notices contained
   in these files, may not be deleted in the course of making such
   alterations.


PREREQUISITES

Hardware: IBM-PC compatible computer with 80186 processor or better.
    The software can be made to run on an 8086 or 8088 processor,
    but only if you modify the assembly language file INNERKER.A
    to replace the PUSHA and POPA instructions.  Other alterations
    might be necessary - the software has not been tested on those
    processors.

    PMOS contains a number of device drivers which might have to be
    rewritten to suit your own hardware configuration.  The software
    seems to work on most "standard" configurations, but testing
    has not been extensive enough to check all possibilities.

Operating system: This software has been developed using Microsoft's
    MS-DOS version 5.  Since PMOS "takes over" the machine once a
    program is running, there are few operating system dependencies;
    but a small number of DOS calls (mainly during module initialisation)
    remain.

    Programs using PMOS will run successfully in an OS/2 DOS session
    provided that they don't depend too critically on precise timing
    and that they don't try to violate the OS/2 protection constraints.
    The PMOS disk drivers won't work under OS/2, but an alternative
    FileSys module is provided to get around that problem.

    PMOS has not been tested under Microsoft Windows.

Compiler: The software has been compiled and tested with TopSpeed Modula-2.
    (TopSpeed is a registered trademark of Clarion Software Corporation.)
    The installation and usage notes in this document assume that
    you are using the TopSpeed compiler.  (Warning: if have the
    TopSpeed compiler without the TechKit option, you will not be
    able to modify the assembly language components.)  Although
    reasonable attempts have been made to keep the code portable, you
    will probably find that you have to do a little editing to make
    this software compile using other compilers.  In particular, the
    assembly language components will certainly need to be changed.

    Experienced programmers will find it feasible to port PMOS to
    work with other compilers; but it's not a job for the
    inexperienced or faint-hearted.


INSTALLATION

The installation procedure assumes that you are going to install
PMOS in the directory C:\PMOS, and that you are installing from
drive A:.  If this is not the case, make appropriate modifications
to the procedure.

(If you're reading this, you've presumably already worked out how
to do the unzipping.  Check these instructions anyway.)

1. Create a directory C:\PMOS.  This should initially be empty,
   unless you are updating an earlier version of PMOS.

2. Use your favourite unzipping utility to unpack the PMOS20.ZIP
   file.  The file was created with Info-Zip, but up-to-date
   versions of PKUnzip should also work.  Older versions of
   PKUnzip might not work.

At this stage, you have everything you need, but you'll probably
want to recompile with different optimization options.  This
is covered in the following section.


REBUILDING THE LIBRARY AND/OR OBJECT MODULES

In addition to the source files, you will find several project files
(which can be distinguished by a .PR extension), and several redirection
files (all called TS.RED).  These are for the use of the TopSpeed
compiler.  If you have some other compiler you can ignore them, and
ignore the instructions in the rest of this section.

You may wish to tailor the system by changing such details as the
optimisation options and the run-time checking.  There are two
alternative methods for recompiling the entire system:

(a) The project file PMOS.PR in the PMOS\OBJECT directory is for
    rebuilding all of the object files.  The object files are left
    in the same directory.

(b) The project file PMOS.PR in the PMOS\LIB directory rebuilds the
    object files, as above, and also creates a library PMOS.LIB.
    The library file is left in PMOS\LIB, and the object files are
    left in PMOS\OBJECT.

The fastest way to re-build everything is to go to the PMOS\LIB
directory and use the command
           TSC/M PMOS

Whether you use the library or directly use the object files is a
matter of personal preference.  If you want to use the library,
the project file for your own project must contain a line
         #pragma link(pmos.lib)
and in that case you can afford to delete all of the object files
from the PMOS\OBJECT directory.  Alternatively, you can use the object
files directly and delete the entire contents of PMOS\LIB.

Whichever method you use, note that:
 - the "mthread" memory model is the only memory model for which
   PMOS is known to work.  If you use any other memory model, there
   is a risk of getting non-reentrant library procedures, which can
   cause multitasking programs to crash mysteriously.
 - the source files include three assembly language modules.  If
   you don't have the TopSpeed assembler (which is part of the TechKit),
   you might not be able to get PMOS to work.


IF YOU DON'T HAVE THE TOPSPEED COMPILER, OR IF YOU DON'T HAVE
THE TOPSPEED TECHKIT

... then you will have to find replacements for the three assembly
language modules InnerKernel, LowLevel, and RandCard.  You will find
more portable (but slightly slower) versions of RandCard and LowLevel
in the directory PMOS\SOURCES\SPECIAL.  I haven't yet managed to find
a way to replace InnerKernel; the solution will almost certainly
require some changes to module TaskControl, but it's not yet obvious
to me how to do this without any assembly language programming.

NOTE: if you replace LOWLEVEL.A by SPECIAL\LOWLEVEL.MOD, make
sure that you also replace LOWLEVEL.DEF by SPECIAL\LOWLEVEL.DEF.
The "standard" version of LOWLEVEL.DEF makes extensive use of the
TopSpeed pragma system, and is nonportable.

Because PMOS was developed at a time when a standard for Modula-2 had
not yet been adopted, you will probably find that miscellaneous other
changes are needed to a variety of modules, because of small differences
between different Modula-2 compilers.  Most of the changes are likely
to be straightforward, but watch out for one problem area: if your
compiler does not support the LONGCARD data type (for 32-bit cardinals),
you are likely to need major changes to some modules.


WHAT'S IN THE DIRECTORIES

After you have installed PMOS, you will have the following directories.

      PMOS
          This README and some batch files.

      PMOS\ACCOUNTS
          A separate package which is described in the README file in
          that directory.  This directory can be deleted if you don't
          want the separate package.

      PMOS\CONTROL
          A project file to build a control systems laboratory program.
          May need modification to fit your own needs.  Can be ignored
          by most users.

      PMOS\CONTROL\SOURCES
          Source files for the control laboratory program.

      PMOS\DOC
          Some documentation files.

      PMOS\LIB
          This directory is to hold the library file PMOS.LIB.  You
          don't need it if you plan to work directly with object files.

      PMOS\OBJECT
          This directory is for the main PMOS object files.  It is
          initially empty.

      PMOS\SOURCES\GENERAL
          Most of the PMOS source files.

      PMOS\SOURCES\SPECIAL
          Alternative versions for some of the PMOS source files.
          Useful if you want to port PMOS to another compiler, but
          can be ignored otherwise.

      PMOS\SOURCES\TESTS
          Source files for a few test programs.  Not needed, but you
          might find them useful as programming examples.

      PMOS\SOURCES\UTIL
          Source files for some utility programs.

      PMOS\TESTS
          Project files for making some test programs.

      PMOS\UTIL
          Project files for making some utility programs.

Because PMOS is frequently updated, you might find some other
subdirectories.  Typically these contain things such as temporary
files and new modules which are not yet working; I suggest that
you ignore them.

It is strongly recommended that you not put any of your own files
into any of these directories.  Mixing up your own work with the PMOS
files is potentially very confusing.  The preferred method is to make
a new top-level directory for your own work, and to create a
redirection file TS.RED in that directory to set up the correct path
for finding the PMOS components.


CONTACT INFORMATION

The author of PMOS is

            Peter Moylan
            Department of Electrical and Computer Engineering
            The University of Newcastle, NSW 2308
            Australia.

            Phone: [phone]      (time zone GMT+10)
            Fax:   [phone]
            e-mail:   [e-mail]
                      [e-mail]
                      [e-mail]

The preferred method of contacting me is via e-mail; this will probably
bring a faster response than with paper mail.

If you find PMOS useful, please register yourself as a user by sending
me a note.  (Include both e-mail and postal addresses, especially if
you have a hard-to-reach e-mail address.)  It won't cost you anything,
but it will let me contact you with news of corrections and new versions.

If you find any faults in PMOS, or would like to suggest desirable
new features, please let me know.  I am also interested in hearing
about ports of PMOS to other compilers.

You have permission to upload the PMOS package to an archive site
(subject, of course, to any conditions which might be imposed by
the owner of the archive site).  Please let me know if you do so,
so that I can keep track of where updates should be sent.