SURAK v0.1 (System & User Rpl Algorithms Kernel)
--------------------------------------------------------------------------

Introduction
------------

        This is the first general pseudo-multitasking system for the
HP48 (AFAIK, at last). Note that it is NOT an end user product: a library
(#810) is provided, but if you are not a System RPL expert you'll probably
find the whole thing very dissapointing, due mostly to the slowness, lack
of error protections and (possible) unstability of the program. Being a
System RPL expert does not guarantee your satisfaction, either: you might
find my code trivial and/or clumsy. It is: much rewriting will be necessary
to achieve a more elegant version. But, heck, it is v0.1!!

        So, what's the point of this software? Primarily, the result of a
personal challenge. Back in the sixties computers with less horsepower than
the HP48 were multiprogrammed. Couldn't do I the same with my trusty 
calculator? In second place, it is the result of my courses on Operating
Systems and Computer Architecture. Lacking time to fiddle with PC's, I
wondered whether it would be possible to program a portable platform (i.e.
the HP48) to show concepts like coroutines, time-slicing, mutual exclusion...
The answer (to some extent) is this library. The following documents the
routines (visible ones).

        By the way, Surak was (will be? ;-) the philosopher that first
postulated total logic in Vulcan... I just couldn't resist... I'm sure it's
a copyrighted name, but this isn't a commercial product. You can use the
source code as you like, but please, keep me informed of your achievements
and be sure to mention my name in any projects based in this code. Thank you.


Library routines
----------------

KERNEL ( proc1 .. procn %n -> ? )
        Accepts n processes (in fact n secondaries, no matter whether they
        are user or system RPL) and their count, and evaluates them 
        concurrently in some order. All process must signal their
        terminations with TERMINATE (see below) in order to the system to
        finish its execution. If a process reaches its end and no TERMINATE
        has been issued, a Try To Recover Memory? event will surely occur.

NEWPROCESS ( proc -> )
        Accepts a secondary and includes it in the multitasking scheme
        (does not transfer execution to it -- rather it becomes eligible
        for execution to the system routine, by queuing it).
        This command has no sense in a program not to be executed by KERNEL.

TRANSFER ( #origin #destination -> )
        Accepts two bints denoting the PIDs of the process making the
        call and the one receiving control. Although this is a visible
        command, it is of no use outside the library code in its current
        form... Some future version will correct this.

TERMINATE ( -> )
        Signals completion of a process, which allow the system to recover
        the space assigned to it in memory, and changes its PID to zero,
        therefore aborting any future TRANSFER of control inside KERNEL.


The internals of the code contain some more routines that I have not time
right now to document. However, there are no strange entry points in the
code (only an unsupported-static one, RROLL), and anybody with a basic
understanding of System RPL can read through it without difficulties 
(except for the routines handling the return stack, may be... That was
the only really difficult part to program).

Please note that I can't be held responsible for your data loss. This is
a pure hacker's tool, intended to push the limits of what's possible with
this wonderful calculator, and to boldly go... Well, you know what I mean.
Have fun (at least the same I had programming this), and don't hesitate
to email me for questions, bug reports (the whole program might be a bug,
though) and suggestions. You can also contribute to improve this tool in
many ways, and your help will be much appreciated.

        My email: tel96079@lab.dit.upm.es
        Alternative: eco@dat.etsit.upm.es (this is a shared account; please
                                        include my name in the Subject: line)

Please consider I am a student with other things to worry about other than
the HP48... Mainly exams... So be patient in getting me to answer.
-----------------------------------------------------------------------------

                                                        Ivan Rivera
                                                        (­viva Bruckner!)