
    *******************************************************
    *                                                     *
    *  ShowMem4 - The Displayer - runs as .PRG _or_ .ACC  *
    *  Copyright 1988 John Eidsvoog                       *
    *  Revision date: Friday, February 8, 1991            *
    *                                                     *
    *******************************************************

  This program is Freeware.  It may not be sold or distributed
  commercially without my written permission.  You may freely distribute
  it otherwise as long as the files are included in their entirety with
  no modifications. 

-----------------------------------------------------------------------

Included files:

   SHOWMEM4.PCC   The Program/Accessory
   SHOWMEM4.TXT   This text file


About ShowMem4
--------------

ShowMem4 is specially written so that it can be run as either an
accessory _or_ a program.  All you have to do is change the name (using
Show Info) so that the extension (last three letters) is .ACC for an
accessory, or .PRG for a program.  For this reason, I've ARCed ShowMem4
as SHOWMEM4.PCC so that you'll read this doc to find out why. 

ShowMem4 allows you to examine the GEMDOS memory descriptor lists.  The
locations of these lists in memory is not documented by Atari.  There is
a search routine that should find these lists in all ROM versions
(including future ones).  If this search should fail, you will be
alerted that this is an unknown ROM. 

You may list the information to the screen or to a printer.  This is
selected from the initial alert box.  The listing will include all
allocated memory blocks, followed by all memory free blocks.  If you
hold down the 'Alternate' key when you select the output device, you
will also get the memory descriptor waiting list (this is my name for it
as until recently its very existence was undocumented).  It is now
documented as _root, or a pointer to the OS pool, although the new beta
test ROMs seems to contain a pointer to a null.  When GEMDOS splits a
block into two smaller blocks, it uses this list to get a new descriptor
location.  When two contiguous blocks are merged, the unused block is
put back in this list.  For this reason, the entries in this list may or
may not contain any useful information. 

The leftmost column will show the decimal size of each block as well as
a total for each type of memory blocks.

While the listing is scrolling on the screen, you may pause/continue by
using the mouse button. 

ShowMem4 now works correctly on TOS 1.4 and later.  Previously you may
have had to run it twice in order to display a valid listing or it may
have even crash upon running the first time. 

------------------------------------------------------------------------

The structure of a memory descriptor is as follows:

        long  pointer to next descriptor in list or zero (end of list)
        long  starting address of the block
        long  number of bytes in block
        long  pointer to base page of block's owner

(This information is not documented by Atari and you should not rely on
its validity as they are free to change it at any time.)

------------------------------------------------------------------------

One point that should be raised about free memory, is that when GEMDOS
returns the bytes available via Malloc(-1), GEMDOS returns the size of
the largest available block, _not_ the total available memory.  ShowMem
is the only tool (to my knowldege) for the ST that will show you the
true total available memory.  Of course, much of this memory is unusable
because it is comprised of many small 'holes' in memory, too small to
use. 


John Eidsvoog
