Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/612b.lha/Bovs_v1.0/Bovs.doc.pp/Bovs.doc

Text File | 1992-03-01 | 25KB | 488 lines

                                   Bovs
                                Version 1.0
                        Bryan's Overlay Supervisor
                         Copyright 1992 Bryan Ford


                                Disclaimer
                                ~~~~~~~~~~

    This program is provided "as is" without warranty of any kind, either
expressed or implied, including, but not limited to, the implied warranty
of fitness for a particular purpose.  The entire risk as to the results,
reliability and performance of this program is assumed by you.



                               Distribution
                               ~~~~~~~~~~~~

    Bovs may be freely distributed as long as it is complete (none of the
files listed below are left out), all of the files are unmodified, and no
charge is made for such distribution other than a small fee to cover the
cost of copying.  (In effect, no profit may be made through distribution of
this program).  You may modify this code for your own personal use, but you
may not distribute modified versions.  (If you improve Bovs, just send your
modifications back to me - I'll incorporate them into the master, giving
appropriate credit to you, and we won't have hundreds of different versions
of Bovs floating around.)

    You may use the object code derived from this source code, or your own
modified version of this source code, in your own public domain, freeware,
shareware, or otherwise freely distributable programs, as long as you state
that you used Bovs and mention the name of its author (Bryan Ford)
somewhere in your documentation.  You do not need to obtain any kind of
license to use it in freely distributable software.

    If you want to distribute Bovs or any modified version of it, in either
source or object form, with or in a commercial package, you must first
obtain a license from me (Bryan Ford).  The cost of the license will be
equal to twice the retail price of the commercial program in which Bovs is
used.  (This cost covers the license fee of MemMan, which Bovs uses and
requires.)  Additionally, you must send me a copy of the program as soon as
it is finished and released.  The license fee covers all future versions of
your program; however you must send me copies of any major updates you
release afterwards, if they still use Bovs.  This license cost will never
increase, but I reserve the right to decrease or eliminate it.

    The Bovs distribution must contain the following files, complete and
unmodified:

        Bovs.doc        Bovs documentation (this file)
        Bovs.o          Linkable version of Bovs (assembled with OVERLAY=1)
        Bst.o           Same, without overlay support (assembled with OVERLAY=0)
        Bovs.h          Header file for SAS/C programs
        Bovs.asm        Source code for Bovs (A68k)

        MemMan/MemMan.doc       MemMan documentation
        MemMan/memman.library   MemMan runtime library
        MemMan/MemMan.o         Linkable version of MemMan
        MemMan/MemMan.fd        Entrypoints for memman.library
        MemMan/MemMan.h         Header for C programs using MemMan
        MemMan/MemMan.i         Same, for assembly language
        MemMan/MemMan.asm       Source to MemMan (A68k)
        MemMan/MemManLib.asm    Source to memman.library interface (A68k)
        MemMan/Macros.i         Macros you'll need for the above two files
        MemMan/LMKfile          SAS/C makefile for MemMan
        MemMan/test             Program to test memman.library
        MemMan/test.c           Source for MemMan test program



                               Introduction
                               ~~~~~~~~~~~~

    Bovs (pronounced "boffs") is an overlay system designed to replace the
standard overlay system supplied with SAS/C.  It acts as both overlay
supervisor and startup code.  It provides many powerful features that the
standard SAS/C startup code and overlay supervisor don't provide.  It is
intended especially for large applications which need flexible and
efficient use of memory.  It is used in my Shareware music player,
MultiPlayer.

    Bovs currently requires SAS/C's linker, BLink (or a very compatible
linker, if there is such), to create overlaid files.  However, other than
that, SAS/C is not necessarily needed: you can write programs that use Bovs
in assembly language or any other language that supports register arguments
and the standard Amiga object file format.

    Programs that use Bovs can be started from Workbench or the CLI.  Both
1.3 and 2.0 are supported, but when run under 2.0 Bovs supports
command-line parsing with ReadArgs().  If started from the CLI, Bovs
detaches and runs your program in a separate process, freeing up the
original CLI.

    Instead of the standard, rigidly-structured, hierarchially-organized
overlay system that standard Amiga overlay systems use, Bovs uses a very
flexible overlay method based on dynamic memory caching.  When overlaid
code is called, the overlay node in which it is contained is loaded in if
necessary, and the function is called.  However, overlay nodes are not
flushed from memory when other overlay nodes at the same level are called.
(In fact, Bovs doesn't even use overlay "levels".)  Instead, they remain in
memory and immediately available until the memory they occupy is needed for
something else.

    This is where MemMan comes in.  The Bovs distribution includes MemMan,
a low-memory manager also written by myself, which allows programs to be
called when any call to AllocMem() is about to fail, so they can free
memory they don't need.  (Note that while Bovs currently only supports the
BLink that comes with SAS/C, MemMan can be used by many compilers.  See
MemMan's documentation for details.)  Bovs uses MemMan to unload overlay
nodes that aren't currently in use when the system is about to run out of
memory.

    Therefore, if the user of a Bovs program has lots of memory, Bovs ends
up acting as a "delayed-loading" system, to speed up initial loading and
load other parts of the program only when necessary.  After all parts of
the program are loaded, if the user doesn't run out of memory, no more
loading is done and calls to overlaid functions are instantaneous.

    To keep track of which overlay nodes are in use and which may be freed
on demand, Bovs uses a system of nestable locks associated with each
overlay node.  When an overlaid function is called, locking is handled
automatically: Bovs locks the overlay node before calling the function,
and unlocks it after the function returns.  However, your program may also
specifically lock and unlock overlay nodes to ensure that they remain in
memory at certain times.



                               Startup Code
                               ~~~~~~~~~~~~

    Before getting into Bovs's overlay management, I'll describe how Bovs
handles startup and exit.  First of all, Bovs may not be used along with
"c.o" or any of the other standard startup code files.  Bovs does not
support SAS's standard C-style memory allocation or file handling
functions, or any other non-trivial standard library functions.  (You can
still use string functions and such.)  Bovs is Amiga-only.

    Bovs is auto-detaching, so when your program is run from the CLI, a
separate process is started for your program and the original CLI is given
back to the user.  (Ever seen an auto-detaching overlaid program before?
I'm pretty sure MultiPlayer was the first.)

    Somewhere in the non-overlaid part of your program (probably your main
module), you'll have to define several variables containing various pieces
of information Bovs needs during startup.  I'll give the C definitions for
these variables; for assembly language, just add an underscore ('_') before
the variable names.

    First, you need to define a longword variable called "stack" which
contains the stack size required for your program.  Note that this value is
only used if the program was loaded from the CLI and thus was detached from
the original CLI process.  If you want a larger-than-normal stack, make
sure you set this variable AND the stack size specified in the Workbench
icon for your program.

    Second, you must define a pointer variable called "procname" which
contains a pointer to a string containing the name for the process created
when auto-detaching from the CLI.  (Note that this is a pointer to a
string, not the string itself.)  Like the "stack" variable, this is not
used when the program is run from Workbench.

    Third, you need to define a longword variable called "priority" which
contains the Exec priority level at which your process is to run.  Unlike
the above variables, this is used when your program is started from either
the Workbench or the CLI.

    Finally, you must define two variables which Bovs passes to AmigaDOS
2.0's ReadArgs() function if your program is run under 2.0.  The variable
"argtemplate" must be a string (not a pointer to a string) containing the
standard argument template.  For example, MultiPlayer's "argtemplate"
variable is "DIRECTORY,PLAY=MODULES/M,PROG=PROGRAM/K,SCREEN/K,NOREQUEST/S,
NOWINDOW/S,NOREXX/S".  The variable "argarray" must be an array of
longwords (it's usually convenient to define it as a structure in C) which
AmigaDOS 2.0 will fill in with the parameters from the parsed argument
template.  I won't go into the details of argument parsing; Commodore's
documentation should suffice.

    In addition to these five variables, you must define the symbol "Main"
("@Main" in assembly language) as a function which will be the entrypoint
of your program.  It must be defined like this:

    void __regargs Main(int arglen,char *argstr)
                              D0           A0

    You may omit the "__regargs" keyword if you are compiling with register
arguments as the default.  In any case, when Main() is called, "arglen"
contains the length of the unparsed command line received directly from
AmigaDOS, and "argstr" is a pointer to that command line.  (Bovs doesn't
separate the command line into separate arguments like the standard startup
code does; the name change from "main" to "Main" is intended to emphasize
this difference.)  If your program is called from the Workbench, "arglen"
will contain zero and "argstr" will contain the Workbench startup message.

    Note that the raw command line is available on entry even if the
command line was also parsed with 2.0's ReadArgs() function.  Under 1.3,
your "argtemplate" will remain unmodified and unused; under 2.0, you'll get
both.  If you want compatibility with both 1.3 and 2.0, you should use the
parameters in "argtemplate" if they have been filled in; otherwise do some
minimal parsing of the raw command line yourself.

    On startup, you don't have any standard input or output streams, so
don't be printing error messages to nonexistant file handles.  However,
your current directory will be whatever the current directory was in the
CLI your program started from, or if you started from Workbench, the
directory containing your program icon.  You don't have to return to this
directory before exiting your program.

    When the Main() function returns, Bovs frees all resources, closes the
executable file, and ends the program.  You can also do this from anywhere
in your program (as long as you're running from the original process Bovs
started you in) by calling BExit(), described later.  Remember, Bovs
provides NO resource tracking like standard C startup code does: you must
free anything you allocate.  (Of course, Bovs will free anything it
allocates.)



                                 Overlays
                                 ~~~~~~~~

    First of all, be warned that the use of Bovs overlays is not completely
transparent.  Even if you're already using overlays in your program,
converting it to use Bovs will require a little work.  How much it requires
depends on your program.  In this document, I'll assume that you are trying
to convert a non-overlaid program into an overlaid program that uses Bovs.
If you have already written an overlaid program, you shouldn't have too
much trouble figuring out what you need to change to convert it to Bovs.

    Your program will have to have at least one non-overlaid object file,
as well as one or more overlaid files.  You don't have to work out any
complicated overlay call tree or anything: all the overlay nodes are on the
same overlay "level", and any combination of them may be loaded at one
time.  Overlay nodes may even call other overlay nodes, although you will
have to fudge a little to get around some of BLink's error checking.

    You'll have to set up a WITH file that you pass to BLink to link your
program.  In it, along with whatever other BLink options you want, supply
an OVERLAY construct that looks something like this:

OVERLAY
window.o windowspec.o
progwin.o progwinspec.o
prefswin.o prefswinspec.o
flashy.o flash.o flashyspec.o
rexx.o
#

    (This is part of MultiPlayer's WITH file.)  All the object files on one
line are linked into the same overlay node: they are loaded and unloaded
together, and they may share data, make no-overhead calls to each other,
and so on.  Each line specifies a separate overlay node.  Note that you
should never use asterisks ('*') before the filenames, as Bovs neither
needs nor supports hierarchial overlays.

    There are certain limitations to what you can do when programming with
overlays.  First, you can't directly reference data in one overlay node
from another overlay node, or from the root (the non-overlaid part of the
program).  The only exception to this (and it's not really an exception) is
if you name your data hunks "__MERGED", in which case BLink will merge the
data into the root node's global data segment, and the data in effect is no
longer associated with the overlay node it was defined in.  Compiling with
SAS/C using the small data model will cause this to happen.  You should
avoid putting too much overlay-node-specific data into the __MERGED hunk,
because that data will be loaded all the time the program runs, even when
the actual overlay node isn't loaded.  (To keep data out of the __MERGED
hunk under SAS/C while still using the small data model, define your
overlay-node-private variables as __far.)

    Bovs imposes very few restrictions on calling functions in overlay
nodes.  Any time an overlaid function is called, BLink reroutes the call
through an entrypoint in Bovs, which loads the required overlay node if it
isn't already loaded, locks it, calls the function, and unlocks it when the
function returns.  Theoretically, functions within overlay nodes could call
functions in other overlay nodes with no problem.  However, BLink has some
very inconvenient checking code that won't let you link a program in which
one overlay node calls another.  (This is based on the assumption that
loading one overlay node causes all other overlay nodes on the same level
to be unloaded - which, with Bovs, is not true.)  For now, unless you find
a way to hack BLink to disable this code (if you do, tell me how!), you'll
have to create "stub" functions in some non-overlaid module to bounce calls
back into other overlay nodes.

    Function calling conventions in Bovs are quite different from those
used with the standard overlay manager.  In particular, no stack parameters
are allowed when calling an overlaid function from outside the function's
overlay node (when BLink has to route the function through Bovs).  This is
because Bovs has to keep some information on the stack during the call so
it can unlock the overlay node on returning.  (It can't just "load and
jump" like the standard overlay supervisor can.)  The only parameters that
are guaranteed to get to the called function are register parameters passed
in A0 and A1.  (In SAS/C, with register arguments active, this amounts to
the first pointer-type parameters; if you want to pass value parameters,
just convert them them to void pointers.)  In addition, the register A4 is
passed through to allow easy use of the small data model.

    If you pass register parameters to overlay functions when using Bovs,
you'll get a bunch of annoying but meaningless warning messages from BLink
telling you that the register parameters will get destroyed, because it
thinks that overlay functions are supposed to be called with stack
parameters.  For now, just let the warnings roll up your screen; I'm trying
to get SAS to put an option in BLink to disable this checking, but so far
I've had no luck.

    At this point things start getting really unconventional.  When an
overlaid Bovs function is called, it actually receives one extra parameter
that the caller never passed to it.  This parameter is passed in D0 (just
define it as a 'long' in a SAS/C function prototype), and contains a
"handle" on the overlay node in which the function resides.  This handle is
only valid throughout that function call, unless the function locks the
overlay node into memory with LockOverlay(), described later, before
returning.  A valid handle passed to you will never be zero (unless you are
using "Bst" instead of "Bovs" and have overlays disabled - this is
described later), but other than that you can't assume anything about what
it actually is.

    At this point, you should be able to implement simple overlaid programs
using Bovs.  Bovs also has some extra features to make your programs sleek
and efficient, which are described in the following sections.



                                 Functions
                                 ~~~~~~~~~

    Bovs defines a few external functions which you may call during your
program for various purposes.  Besides these, since MemMan must be linked
into any program that uses Bovs, you may also call MemMan's memory
management functions.  Do not call MMInit() or MMFinish() from your program
- Bovs does that for you.  However, if you use MemMan directly, you must be
sure to remove all MMNodes before terminating your program.  (See
MemMan.doc for details on using MemMan.)


    void BExit(void)

    Call this function to terminate your program.  Unlike standard exit
functions, BExit() does not take any kind of return code: Workbench doesn't
care about return codes, and the CLI process that started you no longer
even knows that you exist, so there's really nobody to see your return code
anyway.  Calling BExit() is effectively the same as returning from your
Main() function.

    Of course, since Bovs does no resource tracking, you must be sure to
free all resources before calling BExit().  Also, it may only be called
from the original process that Bovs gave you.


    void LockOverlay(long ovhan)
                           D0
    void UnlockOverlay(long ovhan)
                              D0

    Given an overlay handle passed by Bovs to one of your overlaid
functions, LockOverlay() will lock the overlay node containing that
function in memory.  It will not be unloaded until you unlock the overlay
node.  LockOverlay() calls may be nested, and every call to LockOverlay()
must be paired with exactly one call to UnlockOverlay().  The only
exception to this rule is that you don't have to unlock every locked
overlay node before your program exits: Bovs will unload all loaded overlay
nodes before exiting, locked or unlocked.  In any case, you must NEVER try
to unlock an overlay node that you haven't already locked.

    You may only call LockOverlay() on a given overlay handle from within
the function that was passed the handle, or from within a sub-function that
it calls.  You MAY NOT pass an overlay handle back from an overlay function
to the function that calls it.  In other words, the overlay handle is ONLY
valid during the call to the overlaid function, unless you lock it within
that function.

    When using LockOverlay() and UnlockOverlay() to ensure that a certain
overlay node stays in memory at certain times, it is permissible for the
main module or other overlay nodes to access the overlay node's data
(indirectly through pointers, since direct references are not allowed), or
to call functions in the overlay node through function pointers.  This can
be desirable, for example, if you have some function that is very
frequently called and you don't want the slight extra overhead of running
through the overlay supervisor every time the function is called.  However,
any time "outsiders" access a node's data or functions this way, you must
be SURE that the overlay node is locked at the time, so it doesn't
disappear on you.

    You may call UnlockOverlay() from anywhere in your program, as long as
you are sure the overlay handle you're passing to it is valid and locked,
and you're sure that the call will not pull out the carpet from under
you.  To put it in simpler terms, an overlay node may be unlocked by (a) an
"outsider" who has been given the overlay handle, or (b) a function within
the overlay node which was called normally through the overlay supervisor
(not directly through a function pointer).  Since functions called through
function pointers are not automatically locked by Bovs throughout the call,
if such a function were to unlock the last lock on its own overlay node, it
could be unloaded while the function is still running. The only time when
you may unlock the last lock on an overlay node from within such a function
is in assembly language, if the call to UnlockOverlay() is done with a JMP
instruction, causing the call to UnlockOverlay() to return directly to
whatever "outsider" called the function in the first place.

    If this all sounds a little complicated at this point, don't panic:
you only need to worry about this if you're using function pointers called
by external modules.  If you stick to normal functions, there is not much
you need to worry about.


    long ResCall(void *routine,void *arg1,void *arg2)
     D0                   A2          A0         A1

    This function is a little gimmick that you might find useful for
creating sleek, fast programs.  It is used to call overlaid functions in a
way slightly different than normal.  If some part of the program wants to
call a function in another overlay node, normally it makes a call normally,
and BLink reroutes the call to go through Bovs.  However, instead of
calling the function directly, you can pass a pointer to it (which BLink
turns into a pointer to one of its dynamically created rerouter routines)
to ResCall, along with the parameters "arg1" and "arg2" which you would
normally pass to the real function in A0 and A1.  ResCall then calls the
function normally, with the parameters that you specify.

    If the overlay node containing the needed function is already loaded,
then the function is called normally, and its return value (whatever it may
be) is passed back in D0, as usual.  However, if the overlaid function is
NOT resident, the function is not called at all, and Bovs returns with zero
in D0 immediately, without loading the overlay node.

    Thus, ResCall provides a simple and convenient way to call an overlaid
function only if that overlay node is already resident.  I have found this
useful in many cases, but I'll let you figure them out yourself.  In any
case, if the overlay node is resident and the function is called, all
standard overlay function calling and locking conventions still apply.



                                   Bst.o
                                   ~~~~~

    The alternate object file "Bst.o" (pronounced "beast") can be used in
place of "Bovs.o" if you want Bovs's startup features without its overlay
system, or if you want to create a non-overlaid version of a program that
is normally overlaid.  Your normally overlaid functions may be called with
anything (including zero) in D0, since they are not called through the
overlay supervisor, and while the LockOverlay() and UnlockOverlay()
functions still exist in Bst, they do nothing.  Therefore, as long as
you're careful, you should be able to link your program in both overlaid
and non-overlaid versions, and have it perform exactly the same either way.
MultiPlayer's registered distribution, for example, contains both overlaid
and non-overlaid versions of the MultiPlayer program, to best suit the
user's preferences.



                                  History
                                  ~~~~~~~

1.0 (18-Feb-92)
        First public release.



                              Contact Address
                              ~~~~~~~~~~~~~~~

    I tend to move around a great deal, so mail sent directly to me
sometimes has a hard time catching up.  If you want mail to reach me (it
may take a while, but it WILL reach me), send it to this address:

        Bryan Ford
        8749 Alta Hills Circle
        Sandy, UT 84093

    I can be reached more quickly (for the time being anyway) on the phone
or through one of the electronic mail addresses below:

        [phone]
        [e-mail]
        [e-mail]
        [e-mail]

    If you want to get something to me through the mail more quickly, FIRST
call or E-mail me to make sure I'm still here, then send it to this
address:

        Bryan Ford
        27104 Ballif Hall
        University of Utah
        Salt Lake City, UT 84112