home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / utilities / gmdev300.lha / VMem.doc < prev    next >
Encoding:
Text File  |  1992-12-06  |  11.9 KB  |  368 lines

  1. TABLE OF CONTENTS
  2.  
  3. vmem.library/General_Information
  4. vmem.library/VMAllocMem
  5. vmem.library/VMAllocVec
  6. vmem.library/VMAvailMem
  7. vmem.library/VMFreeMem
  8. vmem.library/VMFreeVec
  9. vmem.library/VMGetPageSize
  10. vmem.library/VMTypeOfMem
  11.  
  12. vmem.library/General_Information             vmem.library/General_Information
  13.  
  14.                       *** GENERAL INFORMATION ***
  15.  
  16. The General Purpose of vmem.library is to make a virtual memory handler
  17. available to any application writer while keeping things as transparent
  18. and easy as possible. Any application using vmem.library will work with
  19. or without actually having installed virtual memory. No need for huge
  20. checks all over the code.
  21.  
  22. As soon as GigaMem is installed, all applications using vmem.library will
  23. take advantage of it. If other virtual memory systems will appear on the
  24. market (e.g. from Commodore), vmem.library will be updated to support it.
  25. Your application will take advantage immediately without a change.
  26.  
  27. RESTRICTIONS:
  28.   There are a few restrictions due to the nature of virtual memory
  29. itself, not this specific implementation of virtual memory.
  30.  
  31. 1) You must not call any of the library functions while Disable(), Forbid()
  32.    or from interrupts.
  33. 2) Memory allocated via any call of vmem.library MUST NOT be accessed
  34.    while Disable(), Forbid() or made available to any task other than
  35.    the one which did the allocation. This includes message ports,
  36.    semaphores, public lists or list entries, IO requests, interrupt
  37.    structures etc.
  38.    This also includes ANY IO from or to this memory especially DOS.LIBRARY.
  39.    You MUST do buffered IO from and to this memory..
  40.    It is possible though to use VMTypeOfMem(memoryblock) to see if this
  41.    restrictions apply to the memory you got: If VMTypeOfMem returns TRUE
  42.    (non-zero) you MUST CONSIDER these restrictions.
  43. 3) Only DATA may be stored in virtual memory, no CODE. Therefore you
  44.    should not LoadSeg() (which is a DOS call and therefore illegal anyway)
  45.    to this memory or copy/decrunch any piece of code to it.
  46.  
  47. EFFICIENCY:
  48.   Some points (especially the data structres) have to be considered
  49. to get maximum performance out of virtual memory.
  50. Let's take an editor or word processor as example:
  51.  
  52. 1) Do not go through the entire buffer unless you absolutely have to.
  53.    For example, if the user adds some lines to the beginning of a long
  54.    text, it is unacceptable that each time he (or she) presses the return
  55.    key (or even worse: any key.), the application moves up the entire
  56.    document in memory, thereby causing the entire memory space to get
  57.    transferred to and from disk. Use a scheme with buffers of a medium
  58.    size, say 16K. To add some text at the beginning, simply add a new
  59.    buffer. The buffers need not be full, not even most of them - we have
  60.    enough memory now. If two consecutive buffers are less than half
  61.    occupied, you may very well melt them into one and throw away the other.
  62. 2) Same subject: If you keep an array of pointers to lines (editors) or
  63.    paragraphs (word processors), keep it in a seperate array. DO NOT
  64.    SCATTER THESE POINTERS OVER THE LARGE BUFFER. The pointers should scan
  65.    through without causing multiple pagefaults.
  66. 3) Set the MEMF_CLEAR for Virtual Memory only when this is a must. You
  67.    should be able to never use MEMF_CLEAR for Virtual Memory.
  68.    Reason: The usage of MEMF_CLEAR may result in a speed penalty due to
  69.    the time needed for clearing a large memory block.
  70. 4) When you go through large parts of the buffer (typically by searching for
  71.    some item), try to avoid any write access wherever possible.
  72.    Reason: Going through large memory space is always time consuming. If
  73.    you do both read- and write access, then all the pages have to be both
  74.    read from disk and written back, thereby more than doubling the amount
  75.    of time spent waiting for disk.
  76.  
  77.  
  78. vmem.library/VMAllocMem                               vmem.library/VMAllocMem
  79.  
  80.    NAME
  81.     VMAllocMem -- allocate (virtual) memory given certain requirements
  82.  
  83.    SYNOPSIS
  84.     memoryBlock = VMAllocMem(byteSize, attributes, flags)
  85.     D0             D0       D1           D2
  86.  
  87.     void *VMAllocMem(ULONG, ULONG, ULONG);
  88.  
  89.    FUNCTION
  90.     This is the memory allocator for virtual memory aware
  91.     applications.
  92.  
  93.     Memory is allocated based on requirements and options.    Any
  94.     "requirement" must be met by a memory allocation, any "option" will
  95.     be applied to the block regardless.  VMAllocMem will try all memory
  96.     spaces until one is found with the proper requirements and room for
  97.     the memory request.
  98.  
  99.    INPUTS
  100.     byteSize - the size of the desired block in bytes. (The vmem.library
  101.         will automatically round this number to a multiple of
  102.         the system memory chunk size)
  103.  
  104.     attributes -
  105.         requirements
  106.  
  107.         If no flags are set, the system will return the best
  108.         available memory block (either virtual memory or not).
  109.  
  110.         Setting any atrribute (e.g. MEMF_CHIP) will result in a
  111.         normal AllocMem(). Do not use VMAllocMem() when you
  112.         need one of these attributes since it doesn't make much
  113.         sense with virtual memory. This is only supported for
  114.         compatibility reasons.
  115.  
  116.         options
  117.  
  118.         MEMF_CLEAR:    The memory will be initialized to all zeros.
  119.                 Avoid MEMF_CLEAR for performance reasons.
  120.  
  121.     flags - Special virtual memory flags.
  122.  
  123.         VMEMF_VIRTUAL:    Return ONLY virtual memory.
  124.                 DO NOT SPECIFY VMEMF_VIRTUAL unless you know
  125.                 exactly what you are doing. If VMEMF_VIRTUAL
  126.                 is set, VMAllocMem() will fail on machines
  127.                 that do not have virtual memory.
  128.  
  129.         VMEMF_VIRTPRI:    Return preferably virtual memory. Return
  130.                 physical memory only if no virtual memory
  131.                 is left. You should not set this flag
  132.                 since this overrides the user's setting.
  133.  
  134.         VMEMF_PHYSPRI:    Return preferably physical memory. Return
  135.                 virtual memory only if no physical memory
  136.                 is left. You should not set this flag
  137.                 since this overrides the user's setting.
  138.  
  139.         VMEMF_ALIGN:    Try to return a memory block aligned to
  140.                 a page start. There is normally no need
  141.                 for this. Alignement is done automatically
  142.                 for allocations requesting for a multiple
  143.                 of the page size (SEE ALSO VMGetPageSize()).
  144.                 You must not depend on the alignment as it
  145.                 may fail on low memory conditions which
  146.                 will result in a misaligned allocation.
  147.                 Note: VMAllocVec will add 4 to your request
  148.                 to track the size.
  149.  
  150.    RESULT
  151.     memoryBlock - a pointer to the newly allocated memory block.
  152.         If there are no free memory regions large enough to satisfy
  153.         the request, zero will be returned.  The pointer must be
  154.         checked for zero before the memory block may be used.
  155.  
  156.    WARNING
  157.     The result of any memory allocation MUST be checked, and a viable
  158.     error handling path taken.  ANY allocation may fail if memory has
  159.     been filled.
  160.  
  161.    EXAMPLES
  162.     VMAllocMem(0xA000000, NULL, NULL)  - Allocate 10 Mb of the best
  163.                        available memory
  164.  
  165.    NOTE
  166.     This function MUST NOT be called while Forbid(), Disable() or
  167.     from interrupts.
  168.  
  169.    SEE ALSO
  170.     VMFreeMem(), VMGetPageSize(), AllocMem
  171.  
  172. vmem.library/VMAllocVec                               vmem.library/VMAllocVec
  173.  
  174.    NAME
  175.     VMAllocVec -- allocate (virtual) memory and keep track of the size
  176.  
  177.    SYNOPSIS
  178.     memoryBlock = VMAllocVec(byteSize, attributes, flags)
  179.     D0             D0       D1           D2
  180.  
  181.     void *VMAllocVec(ULONG, ULONG, ULONG);
  182.  
  183.    FUNCTION
  184.     This function works identically to VMAllocMem(), but tracks the size
  185.     of the allocation.
  186.  
  187.     See the VMAllocMem() documentation for details.
  188.  
  189.    WARNING
  190.     The result of any memory allocation MUST be checked, and a viable
  191.     error handling path taken.  ANY allocation may fail if memory has
  192.     been filled.
  193.  
  194.    SEE ALSO
  195.     VMFreeVec(), VMAllocMem(), AllocVec
  196.  
  197. vmem.library/VMAvailMem                               vmem.library/VMAvailMem
  198.  
  199.    NAME
  200.     VMAvailMem -- (virtual) memory available given certain requirements
  201.  
  202.    SYNOPSIS
  203.     size = VMAvailMem(flags, attributes)
  204.     D0          D0     D1
  205.  
  206.     ULONG VMAvailMem(ULONG, ULONG);
  207.  
  208.    FUNCTION
  209.     This function returns the amount of free memory given certain
  210.     attributes.
  211.  
  212.     To find out what the largest block of a particular type is, add
  213.     MEMF_LARGEST into the requirements argument.  Returning the largest
  214.     block is a slow operation (since this may include disk operation).
  215.  
  216.    WARNING
  217.     Due to the effect of multitasking, the value returned may not
  218.     actually be the amount of free memory available at that instant.
  219.  
  220.    INPUTS
  221.  
  222.     requirements - A requirements mask as specified in AllocMem.  Any
  223.                of the AllocMem bits are valid, as is MEMF_LARGEST
  224.                which returns the size of the largest block matching
  225.                the requirements.
  226.  
  227.     currently supported options
  228.  
  229.         MEMF_LARGEST:    Return largest continous block
  230.  
  231.         MEMF_TOTAL:    Return total amount (used and free)
  232.                 Note: For any other memory type than
  233.                 virtual memory, this will require
  234.                 Exec V36 or higher.
  235.  
  236.     flags - Special virtual memory flags.
  237.  
  238.         VMEMF_VIRTUAL:    Consider ONLY virtual memory.
  239.  
  240.  
  241.    RESULT
  242.     size - total free space remaining (or the largest free block).
  243.  
  244.    NOTE
  245.     This function MUST NOT be called while Forbid(), Disable() or
  246.     from interrupts.
  247.  
  248.    EXAMPLE
  249.     VMAvailMem(NULL, VMEMF_VIRTUAL); /* return available virtual memory */
  250.  
  251.    SEE ALSO
  252.     VMAllocMem(), AvailMem
  253.  
  254. vmem.library/VMFreeMem                                 vmem.library/VMFreeMem
  255.  
  256.    NAME
  257.     VMFreeMem -- deallocate (virtual) memory with knowledge
  258.  
  259.    SYNOPSIS
  260.     VMFreeMem(memoryBlock, byteSize)
  261.           A1           D0
  262.  
  263.     void VMFreeMem(void *,ULONG);
  264.  
  265.    FUNCTION
  266.     Free a region of memory, returning it to the system pool from which
  267.     it came.  Freeing partial blocks back into the system pool is
  268.     unwise.
  269.  
  270.    NOTE
  271.     If a block of memory is freed twice, the system will Guru. The
  272.     Alert is AN_FreeTwice ($01000009).   If you pass the wrong pointer,
  273.     you will probably see AN_MemCorrupt $01000005.  Future versions may
  274.     add more sanity checks to the memory lists.
  275.  
  276.    INPUTS
  277.     memoryBlock - pointer to the memory block to free
  278.     byteSize - the size of the desired block in bytes.  (The operating
  279.         system will automatically round this number to a multiple of
  280.         the system memory chunk size)
  281.  
  282.    SEE ALSO
  283.     VMAllocMem(), FreeMem
  284.  
  285. vmem.library/VMFreeVec                                 vmem.library/VMFreeVec
  286.  
  287.    NAME
  288.     VMFreeVec -- return VMAllocVec() memory to the system
  289.  
  290.    SYNOPSIS
  291.     VMFreeVec(memoryBlock)
  292.           A1
  293.  
  294.     void VMFreeVec(void *);
  295.  
  296.    FUNCTION
  297.     Free an allocation made by the VMAllocVec() call. The memory will
  298.     be returned to the system pool from which it came.
  299.  
  300.    NOTE
  301.     If a block of memory is freed twice, the system will Guru. The
  302.     Alert is AN_FreeTwice ($01000009).   If you pass the wrong pointer,
  303.     you will probably see AN_MemCorrupt $01000005.  Future versions may
  304.     add more sanity checks to the memory lists.
  305.  
  306.    INPUTS
  307.     memoryBlock - pointer to the memory block to free, or NULL.
  308.  
  309.    SEE ALSO
  310.     VMAllocVec(), FreeVec
  311.  
  312. vmem.library/VMGetPageSize                         vmem.library/VMGetPageSize
  313.  
  314.    NAME
  315.     VMGetPageSize -- returns current page size
  316.  
  317.    SYNOPSIS
  318.     pagesize = VMGetPageSize()
  319.     D0
  320.  
  321.     ULONG VMFreeMem(void);
  322.  
  323.    FUNCTION
  324.     Returns current page size or default value if no virtual memory is
  325.     installed. This allows applications to consider the current
  326.     page size for efficiency reasons. The page size is a power
  327.     of 2 larger than 256 bytes. (Currently, default page size is 8k)
  328.  
  329.    NOTE
  330.     If no virtual memory handler is installed, returns default value.
  331.  
  332.    RESULT
  333.     pagesize - size in bytes of pages or default page size.
  334.  
  335.    SEE ALSO
  336.  
  337. vmem.library/VMTypeOfMem                             vmem.library/VMTypeOfMem
  338.  
  339.    NAME
  340.     VMTypeOfMem -- determine attribute (virtual or not) of a given
  341.                memory address.
  342.  
  343.    SYNOPSIS
  344.     attribute = VMTypeOfMem(address)
  345.     D0                A1
  346.  
  347.     BOOL VMTypeOfMem(void *);
  348.  
  349.    FUNCTION
  350.     Given a RAM memory address, returns TRUE if the memory address
  351.     is in virtual memory. Otherwise returns FALSE (zero) and you
  352.     may the check with exec/TypeOfMem for the ordinary memory
  353.     attributes (e.g. MEMF_CHIP).
  354.  
  355.     If the address is not in known-space, FALSE will be returned.
  356.     (Anything that is not RAM, like the ROM or expansion area, will
  357.     return FALSE.)
  358.  
  359.    INPUT
  360.     address - a memory address
  361.  
  362.    RESULT
  363.     attributes - Boolean: TRUE if virtual memory. Otherwise FALSE.
  364.  
  365.    SEE ALSO
  366.     VMAllocMem(), TypeOfMem
  367.  
  368.