                           PAL Library version 0.1
                     Copyright (C) 1994 Peter Andersson
                             m8439@sparc2.abc.se


 COMPILING
 ---------

   You will need TASM v3.2 or above and a library manager such as TLIB 
   or LIB to compile the PAL library. Simply run the batch file MAKEIT.BAT.
   Please modify makeit.bat to customise the PAL library. PAL supports C
   compilers that support the _fastcall convention. This calling convention 
   passes the first three parameters to the _fastcall funtion via EAX, EDX 
   and ECX respectivly. The convention also inserts the '@' character 
   infront of each function name. Borland C v4.5+ 32bit compiler supports 
   _fastcall.  When compiling C code using the PAL Library _fastcalls 
   functions you must first define the macro 'FASTCALLS' or else the PAL.H file will not
   define it's functions as _fastcall. With Borland C this may be done using
   the -D switch. For example;

    BCC32 -DFASTCALLS program.c

   If you have standard C calls enabled ( see makeit.bat ) then this allows
   all functions to be also called using the standard C calling convention.
   i.e parameters passed via the stack and each function name is preceded with 
   '_' character. It will also increase the library size by about 1K. 
   MAKEIT.BAT defaults to this setup.

    

 HANDLING MEMORY
 ---------------

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

   MEMORY is a sub memory allocator. It is designed to be used with almost
   all flat memory systems where the normal memory allocator only can provide
   whole pages (4096 bytes).

   All functions use the _fastcall calling convention and they are optimized 
   for the i486 but will also work on a i386. Maximum handled memory size is
   4GB. Each allocated memory block has a 12 byte header. Define DEBUG to let
   checkmem, malloc, realloc and free report errors. You will have to include
   a printf function if you use the DEBUG feature or rewrite it.

 *****************************************************************************
 * OBSERVE: This functions _ARE_NOT_ made for multitasking systems which use *
 * the same address space. If you really need this, be sure to forbid any    *
 * other processes to call any of this functions at the same time.           *
 *****************************************************************************

 How to use
 ----------

   First of all you must add a memory block to the memory allocator. Call the
   system's malloc and pass the returned memory pointer and length of the
   block to the addmem function. This function call can handle as many blocks
   as you want! Remember that addmem uses 40 bytes of every added block and
   the minimum block size you can add is 44 bytes. Each sub allocation uses
   12 bytes + the size you have requested aligned up to the nearest 4 bytes.

   To remove a block, call submem with a pointer to the memory block you added. 
   Don't forget to remove all references to the memory block! This function
   also frees all allocated memory blocks so if you forgot one, don't worry!

   If your program overwrites a memory block header there might be a problem to
   allocate any futher blocks. Use the checkmem function to find the address of
   the faulty header in a memory block. The returned pointer is zero if there
   weren't any errors. OBSERVE: The returned pointer might not always be
   pointing to the corrupted block but to the previous block!

   The functions memavail and maxavail are used to get information on how much
   memory are available and the maximum block size you can allocate. This
   functions are quite handy if there are any memory leaks.




 C LIBRARY
 ---------

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

   This is far from what I would really call a "C library". It is a bunch of
   routines that I have written to be able to work faster and hopefully it
   will help you too. More routines will be added as my work proceeds and
   you are always welcome to add more code to this collection. I will only
   accept assembler for small routines! For larger work, C and C++ are
   accepted as long as they follow the ANSI standard. Your work will, if
   they are accepted, be included with this work. I might rewrite some or
   all of your work so that they will use the same style as the rest of the
   code. You will of course still retain your name and copyright!

   The file routines are in a separate directory as they don't follow the
   ANSI C standard. They work but it might be best to rewrite them so they
   comply to the ANSI C standard.

 How to use
 ----------

   Get a standard C library reference! You'll find everything you need in
   that reference. If you don't know assembler and what a calling convention
   is you're DooMed. If a C routine is missing you can always get the GNU C
   library and compile it with a 32bit C compiler. It might be a good idea
   as my routines tend to be a bit bigger than what a C compiler produces but
   remember that compiled routines _are not_ hand optimized ;-). You'll only
   have to do this once so ask a friend who own a good 32bit C compiler if you
   don't have one.



  Liniking
 ----------

   The entire library is conatined in the file PAL.LIB and of course
   it must be linked in with the program. The linker should be set to
   case sensitive symbol matching. The startup code, C0.OBJ, is not
   inlcuded in PAL.LIB and must be linked seperatly. The startup code
   has been speperated from PAL.LIB as this allows the programmer to 
   have a different start up comfigeration for each application. See the
   actual source code, STARTUP\C0.ASM, for details on customizing
   the start up. 
    
   

 Comment from the author
 -----------------------

   Hopefully this package will be useful for you! If you have any ideas,
   comments or bug reports, don't hesitate to send them to me:

      email: m8439@sparc2.abc.se   or mail: Peter Andersson
                                            C/O Harkonen
                                            Tullingebergsv. 6A
                                            146 45  Tullinge
                                            SWEDEN

  Good luck and don't forget to support free software!

  Regards,

    Peter
