home *** CD-ROM | disk | FTP | other *** search
/ Groovy Bytes: Behind the Moon / groovybytes.iso / GROOVY / SND_TOOL / FUNK108A.ZIP / DOS32V30.ZIP / PAL / README.TXT < prev   
Encoding:
Text File  |  1995-05-27  |  5.6 KB  |  130 lines
  1.                            PAL Library version 0.0
  2.                      Copyright (C) 1994 Peter Andersson
  3.                              m8439@sparc2.abc.se
  4.  
  5.  
  6.  COMPILING
  7.  ---------
  8.  
  9.    You will need TASM v3.2 or above and a library manager such as TLIB 
  10.    or LIB to compile the PAL library. Simply run one of the batch files.
  11.    Running MFAST.BAT will create the PAL library for C compilers that 
  12.    support the _fastcall convention. This calling convention passes the
  13.    first three parameters to the _fastcall funtion via EAX, EDX and ECX
  14.    respectivly. The convention also inserts the '@' character infront of
  15.    each function name. Borland C v4.5+ 32bit compiler supports _fastcall.
  16.    When compiling C code using the PAL Library _fastcalls functions you 
  17.    must first define the macro 'FASTCALLS' or else the PAL.H file will not
  18.    define it's functions as _fastcall. With Borland C this may be done using
  19.    the -D switch. For example;
  20.  
  21.     BCC32 -DFASTCALLS program.c
  22.  
  23.    Running M.BAT will create the PAL library for compilers which DO NOT
  24.    support _fastcall. This will make the library slightly larger (an extra
  25.    1K) and all functions may also be called using the standard C calling 
  26.    convention.
  27.  
  28.     
  29.  
  30.  HANDLING MEMORY
  31.  ---------------
  32.  
  33.  Introduction
  34.  ------------
  35.  
  36.    MEMORY is a sub memory allocator. It is designed to be used with almost
  37.    all flat memory systems where the normal memory allocator only can provide
  38.    whole pages (4096 bytes).
  39.  
  40.    All functions use the _fastcall calling convention and they are optimized 
  41.    for the i486 but will also work on a i386. Maximum handled memory size is
  42.    4GB. Each allocated memory block has a 12 byte header. Define DEBUG to let
  43.    checkmem, malloc, realloc and free report errors. You will have to include
  44.    a printf function if you use the DEBUG feature or rewrite it.
  45.  
  46.  *****************************************************************************
  47.  * OBSERVE: This functions _ARE_NOT_ made for multitasking systems which use *
  48.  * the same address space. If you really need this, be sure to forbid any    *
  49.  * other processes to call any of this functions at the same time.           *
  50.  *****************************************************************************
  51.  
  52.  How to use
  53.  ----------
  54.  
  55.    First of all you must add a memory block to the memory allocator. Call the
  56.    system's malloc and pass the returned memory pointer and length of the
  57.    block to the addmem function. This function call can handle as many blocks
  58.    as you want! Remember that addmem uses 40 bytes of every added block and
  59.    the minimum block size you can add is 44 bytes. Each sub allocation uses
  60.    12 bytes + the size you have requested aligned up to the nearest 4 bytes.
  61.  
  62.    To remove a block, call submem with a pointer to the memory block you added. 
  63.    Don't forget to remove all references to the memory block! This function
  64.    also frees all allocated memory blocks so if you forgot one, don't worry!
  65.  
  66.    If your program overwrites a memory block header there might be a problem to
  67.    allocate any futher blocks. Use the checkmem function to find the address of
  68.    the faulty header in a memory block. The returned pointer is zero if there
  69.    weren't any errors. OBSERVE: The returned pointer might not always be
  70.    pointing to the corrupted block but to the previous block!
  71.  
  72.    The functions memavail and maxavail are used to get information on how much
  73.    memory are available and the maximum block size you can allocate. This
  74.    functions are quite handy if there are any memory leaks.
  75.  
  76.  
  77.  
  78.  
  79.  C LIBRARY
  80.  ---------
  81.  
  82.  Introduction
  83.  ------------
  84.  
  85.    This is far from what I would really call a "C library". It is a bunch of
  86.    routines that I have written to be able to work faster and hopefully it
  87.    will help you too. More routines will be added as my work proceeds and
  88.    you are always welcome to add more code to this collection. I will only
  89.    accept assembler for small routines! For larger work, C and C++ are
  90.    accepted as long as they follow the ANSI standard. Your work will, if
  91.    they are accepted, be included with this work. I might rewrite some or
  92.    all of your work so that they will use the same style as the rest of the
  93.    code. You will of course still retain your name and copyright!
  94.  
  95.    The file routines are in a separate directory as they don't follow the
  96.    ANSI C standard. They work but it might be best to rewrite them so they
  97.    comply to the ANSI C standard.
  98.  
  99.  How to use
  100.  ----------
  101.  
  102.    Get a standard C library reference! You'll find everything you need in
  103.    that reference. If you don't know assembler and what a calling convention
  104.    is you're DooMed. If a C routine is missing you can always get the GNU C
  105.    library and compile it with a 32bit C compiler. It might be a good idea
  106.    as my routines tend to be a bit bigger than what a C compiler produces but
  107.    remember that compiled routines _are not_ hand optimized ;-). You'll only
  108.    have to do this once so ask a friend who own a good 32bit C compiler if you
  109.    don't have one.
  110.  
  111.  
  112.  
  113.  Comment from the author
  114.  -----------------------
  115.  
  116.    Hopefully this package will be useful for you! If you have any ideas,
  117.    comments or bug reports, don't hesitate to send them to me:
  118.  
  119.       email: m8439@sparc2.abc.se   or mail: Peter Andersson
  120.                                             C/O Harkonen
  121.                                             Tullingebergsv. 6A
  122.                                             146 45  Tullinge
  123.                                             SWEDEN
  124.  
  125.   Good luck and don't forget to support free software!
  126.  
  127.   Regards,
  128.  
  129.     Peter
  130.