Virtual-Memory Documentation
                  ============================

GENERAL
-------
What is Virtual Memory (VM) ?
 VM refers to the memory available to a program which exists either in Primary
 Memory (Physical) or in Secondary Memory (Disk). Normally VM space is larger
 Than physical space and it is the task of the processor/OS to switch data
 to and from the disk.
 On 386/486 systems VM exists when working in what is called Protected Mode , 
 The Amiga doesn't support such capabilities , and my functions try to create
 such environment.
 The abstraction used is that of Segments - Blocks of memory of varying size
 which all exist in VM. When you need to use a segment it is mapped to physical
 memory starting at a specific Base Address. If there is no room for a segment
 other segments will be swapped to disk to make room.
 An important concept is that of a PRESENT segment. such segment resides in
 physical memory and has a valid Base Address.

FUNCTIONS
---------
*  InitVirtualMem --
    Initialize a VirtMem structure and allocate physical memory.
    Note that more than one VM space can be created.

    BOOL InitVirtualMem(VM,FName,VirtSize,PhysSize,SegNum)

   Input -
    struct VirtMem *VM  -- A pointer to an empty VirtMem structure.
    char const *FName   -- A pointer to the Disk file name used as swap file.
    ULONG VirtSize      -- Size of virtual memory in bytes (currently ignored).
    ULONG PhysSize      -- Size of physical memory. Allocated by function.
    USHORT SegNum       -- Max number of segments.
   Output -
    returns TRUE if successful , FALSE otherwise.


*  FreeVirtMem --
    Free memory associated with a VM space.

    void FreeVirtMem(VM)

   Input -
    struct VirtMem *VM  -- A pointer to an initialized VirtMem structure.
   Output -
    returns nothing.


*  CreateSegment --
    Add a segment to the system. The segment's contents are unintialized.
    The Segment IS NOT made present (mapped to physical memory).

    struct SegEntry *CreateSegment(VM,Size,Pri)

   Input -
    struct VirtMem *VM  -- A pointer to an initialized VirtMem structure.
    ULONG Size          -- Size of Segment (must be smaller than Physical
                                             memory size).
    SHORT Pri           -- Priority of the segment. Range -128 to 127.
   Output -
    returns pointer to SegEntry if sucessful , NULL otherwise.


*  Access --
    Make a Segment present in physical memory as a neccessary step before
    A read/write operation to this segment.

    BOOL Access(VM,Seg)

   Input -
    struct VirtMem *VM    -- A pointer to an initialized VirtMem structure.
    struct SegEntry *Seg  -- A pointer to a segment that is to be made present.
   Output -
    TRUE is successful , FALSE otherwise.


MACROS
------

NORMALIZE(Seg,Offset) -- Create a physical address from a Base Address in a 
                         Segment and an Offset.
OFFSET(Seg,Full)      -- Calculate an offset from a physical address and the
                         Base Address in the Segment.
DIRTY(Seg)            -- Make Segment DIRTY. A Dirty segment is one that has
                         been changed.
PRESENT(Seg)          -- Check whether a Segment is present.


SWAPPING
--------
When a segment has no room other segments are swapped to disk.
The algorythm for swapping is simple and not very intelligent.
It goes as follows :
 Start Loop
  Find room for the requested segment
  if successful make segment present and return.
  if not find a present segment which has the lowest priority and remove it.
   (if more than one segment has a low priority remove the one that was accessed
    furthest in the past).
 End Loop.

To make the system efficient do the following :
* Set high priority for segments that are accessed regularily.
* Use segment sizes that are whole divisions of physical size.
   e.g with 32K physical memory use 8K/16K segment sizes.


NOTES
-----
* When using pointers work with offsets since absolute addresses change
  every time you swap a segment.
* Remember to set the Dirty bit with the DIRTY macro when you write to
  a segment so it will be updated on disk.
* The system doesn't check for available space on disk. make sure you
  have enough space (Disk Space>=Virtual Size).

COMPILING
---------
The code is written for Aztec C5.2. It should also compile on Lattice.
I use a pre-include file which contains func1_3.h and pragma1_3.h so you
might need to #include these files.
You can either add Virtual.c to your makefile or link the Virtual.o module
if you use Aztec C.


LEGAL STUFF
-----------
The program is Gift-Ware that is if you like it you can send money, software
 poems or anything you like as a gift.
It can be used in any program commercial or otherwise with no charge.


------------
Amit Fridman
s2449558@techst02.discus.technion
Eshkol 15 Yehud
ISRAEL 56000
------------