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