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