home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / Amiga / Workbench / Patches / PoolMem.readme < prev    next >
Text File  |  1998-05-11  |  22KB  |  540 lines

  1. Short:    Memory defragmentizer/AllocP superset
  2. Author:   thor@math.tu-berlin.de (Thomas Richter)
  3. Uploader: thor@math.tu-berlin.de (Thomas Richter)
  4. Version:  1.35
  5. Type:     util/sys
  6. Requires: OS 3.0
  7.  
  8. ______________________________________________________________________________
  9.  
  10.             Version History
  11. ______________________________________________________________________________
  12.  
  13. 1.35:
  14.  
  15. - Added a patch for the AvailMem() function to include the bytes in the 
  16.   scratch list.
  17. - Added the ALLOC32 keyword. See below for caveats! You usually DO NOT
  18.   want this!
  19.  
  20. ______________________________________________________________________________
  21.  
  22. 1.34:
  23.  
  24. - Added the SMALLHEADER keyword. A selected memory block can be set aside
  25.   for the small memory blocks explicitly.
  26. - Fixed a documentation error in the Developpers.readme. Thanks, Dave!
  27.  
  28. ______________________________________________________________________________
  29.  
  30. 1.33:
  31.  
  32. - Removed a bug in the PoolMem shutdown code. The pre-1.33 releases did not
  33.   free the scratch list completely.
  34. - Added the SCRATCHONLY keyword, it installs only the "scratchlist" of
  35.   PoolMem, not the dynamic pools.
  36. - Added the PUDDLESIZE, PUDDLETHRES and SHRINKTHRES keywords to make the 
  37.   parameters of the small memory pool adjustable.
  38. - Rewrote a lot of the kernal routines, mostly for optimizations.
  39. ______________________________________________________________________________
  40.  
  41. To "SaferPatches" users: 
  42.  
  43. To be able to remove PoolMem later on safely, PoolMem must be run AFTER 
  44. SaferPatches has been installed. Same goes of course for all other patches
  45. and the SaferPatches program.
  46. ______________________________________________________________________________
  47.  
  48. Photogenics: I got reports that this program crashes with PoolMem installed
  49. as soon as it is shut down. If anybody knows what's going on with this proggy,
  50. please let me know. It might be worth to check for correct memory allocation
  51. with MungWall and MemSniff.
  52. ______________________________________________________________________________
  53.  
  54. Developpers should check the "Developper.readme" file in this archive. It
  55. contains information about how to allocate and deallocate memory correctly.
  56. THESE AREN'T POOLMEM SPECIFIC INFORMATIONS! ALL OS FRIENDLY PROGRAMS HAVE
  57. TO OBEY THE RULES FORMULATED IN THIS FILE, they aren't my inventions.
  58. ______________________________________________________________________________
  59.  
  60. 1.32:
  61.  
  62. - Rewrote the startup segment completely. All 1.2 compatible code, argument
  63. parser etc... removed. 
  64. - Added a proper version check. PoolMem requires OS 3.0.
  65. - Added the NOMERGE option to avoid merging of FastMem of different speed.
  66. - As a result of the new argument parser, the CHIPFWD option DOES NO LONGER
  67.   include the "INSTALL" option, both arguments should be given.
  68. - The PoolMem algorithms hasn't been changed, though.
  69. - Included new versions of PatchRAM and ShowMem.
  70. - PoolMem 1.31 and above works fine on PowerUp-Systems. Thanks to Andreas
  71.   Kleinert for testing! However, the current version does not yet adjust
  72.   memory correctly for the PowerUp system, that's still left to the ppc.lib
  73.   and AllocP32. Might change in the future, though.
  74.  
  75. ______________________________________________________________________________
  76.  
  77. Compatibility node: The game demo "The Final Odyssey" crashes when PoolMem is
  78. active. Tracing this error down to its roots resulted in an aparent bug in
  79. the memory deallocation function of this game that occurs, too, with MungWall
  80. instead of PoolMem installed. Since EVERY CORRECT PROGRAM is supposed to run 
  81. with MungWall, I WON'T TRY to add a workaround for this bug. Just avoid buggy 
  82. programs, as usual. Thanks to Dirk Neubauer for the hint.
  83. ______________________________________________________________________________
  84.  
  85. 1.31:
  86.  
  87. PoolMem includes a patch for AllocAbs() to be able to allocate absolute memory
  88. from the scratch list. This *should* help to make PoolMem working with the
  89. 68040/68060/ppc library, thus, it should be possible to run PoolMem IN FRONT
  90. of these libraries, i.e. "SetPatch". Would be nice if somebody could sent me 
  91. a report whether this works now or not.
  92.  
  93. Additionally, new versions of the FragMeter and ShowMem program are included.
  94.  
  95. ______________________________________________________________________________
  96.  
  97. Several people reported instabilities when running PoolMem. I can't reproduce
  98. any of these crashes here at my system, thus if you find a REPRODUCABLE crash,
  99. please, please let me know! This version of PoolMem includes debug information
  100. that might help you and me to locate possible bugs. If possible, report bugs
  101. by giving the routine names directly.
  102.  
  103. It has been reported that PoolMem runs astonishingly slow on PowerUp boards.
  104. I've currently no explanation for this, if you've any idea about it, or know
  105. how to fix it - please report!
  106. ______________________________________________________________________________
  107.  
  108. 1.30:
  109.  
  110. This version introduces a major rewrite of all critical routines, especially
  111. the replacement AllocMem() and FreeMem() routine. This might mean that either
  112. old bugs have been fixed or new bugs have been introduced. Anyways, check out
  113. for possible bugs since this is a release with a "0" in the version.
  114. This version might be much faster than the 1.2x version, due to some 
  115. optimizations.
  116. WARNING: Since the new 1.30 release of PoolMem replaces the Exec memory
  117. functions completely, YOU MUST RUN POOLMEM IN FRONT OF OTHER MEMORY PATCHES.
  118. ESPECIALLY, RUN POOLMEM FIRST, MUNGWALL AFTERWARS or Mungwall will be non-
  119. functional.
  120.  
  121. _____________________________________________________________________________
  122.  
  123. 1.22:
  124.  
  125. PoolMem merges now automatically all adjacent memory lists of the same type.
  126.  
  127. ______________________________________________________________________________
  128.  
  129. NEWS FLASH: Found serious bug in XiPaint that caused crashes with PoolMem,
  130. check below for details.
  131. ______________________________________________________________________________
  132.  
  133. 1.21.1:
  134.  
  135. Included a new version of PatchRAM (check PatchRAM.readme for details),
  136. and a new version of the FragMeter program.
  137. _____________________________________________________________________________
  138.  
  139. 1.21:
  140.  
  141. PoolMem flushes now the memory as it should if called by AllocMem(-1,..).
  142. Except that, nothing changed.
  143. _____________________________________________________________________________
  144.  
  145. 1.20:
  146.  
  147. Added the CHIPFWD command. Works like INSTALL but allocates chip mem in
  148. standard (forwards) mode instead of backwards mode. Might solve strange
  149. compatibility problems. Added more sanity checks, included PatchReplyMsg
  150. to create warnings for broken programs.
  151. ______________________________________________________________________________
  152.  
  153. 1.19.1:
  154.  
  155. Changed the name of the DefragMeter to FragMeter because that makes more
  156. sense. Added a chunk count to this program. PoolMem itself unchanged.
  157. ______________________________________________________________________________
  158.  
  159. About PoolMem:
  160.     
  161.     If you run a lot of programs without resetting the system, you'll
  162. usually find that the main memory of the computer is getting "messed up",
  163. split in lots of tiny memory "snippets" that are more or less useless due to
  164. their tinyness. It may happen that you can't start an application even though
  165. enough memory is available - because this memory is too fragmentated to
  166. be of any use.
  167.  
  168. That's the point where PoolMem tries to help you: It manages the main memory
  169. in a way such that it can't get fragmentated too easely. It replaces also
  170. the function of AllocP, which is therefore obsolete.
  171.  
  172. ______________________________________________________________________________
  173.  
  174. Installation and Usage:
  175.  
  176.     Copy the PoolMem program in this archive to the C: directory of your
  177. system partition. Add the following line to your startup-sequence:
  178.  
  179. PoolMem INSTALL >NIL:
  180.  
  181.  
  182. You might also want to install "PatchRAM" which is included in this archive,
  183. too. It modifies the system RAM disk in a way that avoids memory 
  184. fragmentation, too. Another bonus is that the RAM disk will show its true
  185. size from now on, i.e. it won't be no longer 100% full.
  186.  
  187.  
  188. To remove PoolMem later on, open a shell window and enter
  189.  
  190. PoolMem remove
  191.  
  192.  
  193. The complete command template:
  194.  
  195. HELP/S,REMOVE/S,INSTALL/S,CHIPFWD/S,NOMERGE/S,
  196. SCRATCHONLY/S,PUDDLESIZE/N,SHRINKTRHES/N,PUDDLETHRES/N
  197. SMALLHEADER/N,ALLOC32/S
  198.  
  199.  
  200. HELP:            Prints a small overview of the available options.
  201.  
  202. REMOVE:            Remove a previously installed version of PoolMem.
  203.  
  204. INSTALL:        Install the PoolMem patch.
  205.  
  206. CHIPFWD:        Don't allocate big chunks of chip memory in reverse
  207.             direction. 
  208.             NOTE: Starting with 1.32, this is no longer a
  209.             stand-alone option, INSTALL must be given, too.
  210.  
  211. NOMERGE:        Do not attempt to merge adjacent memory blocks of
  212.             the same type. Even if the memory types are equal,
  213.             the physical characteristics of the memory blocks
  214.             might differ (e.g. 32 bit memory vs. 16 bit memory).
  215.             Future versions of PoolMem might respect this.
  216.             fragmentation.
  217.  
  218. SCRATCHONLY:        Do to build memory pools for small block allocations,
  219.             but use the scratch list only.
  220.  
  221. PUDDLESIZE:        Set the "puddle size" for the small block memory pool.
  222.             If an allocation from the small memory pool fails, 
  223.             PoolMem attempts to enlarge the pool by this number
  224.             of bytes. Defaults to 8192.
  225.  
  226. PUDDLETHRES:        Set the "puddle threshold" for the small memory pool.
  227.             Allocations larger than this size are taken from the
  228.             large memory pool instead of the small memory pool.
  229.  
  230. SHRINKTHRES:        Set the "merge threshold". If more than PUDDLESIZE +
  231.             SHRINKTHRES bytes are unused at the end of the
  232.             small memory pool, the pool shrinks and the free
  233.             bytes enter the large pool. Defaults to 4096.
  234.  
  235. SMALLHEADER:        If this option is given, set the memory block of this
  236.             index aside and use it as small memory pool. The
  237.             argument is simply the number of the block in the
  238.             memory list, counting from zero, and can be found
  239.             by watching the output of ShowMem. The topmost memory
  240.             block is number 0, the next below 1 and so on.
  241.             This memory block MUST BE fast memory.
  242.             If this option is given, PoolMem does not try to
  243.             split any fast mem header, only the chip mem is
  244.             split.
  245.             The small memory block is sorted in just before the
  246.             chip memory, but is used for the small memory block
  247.             allocations as long as possible.
  248.  
  249. ALLOC32:        Align all memory allocations to 32 byte boundaries.
  250.             
  251. ______________________________________________________________________________
  252.  
  253. ALLOC32 Caveats:
  254.  
  255.     This keyword keeps memory allocations aligned to 32 byte boundaries,
  256.     which might be useful if dealing with PPC hardware - by using this
  257.     keyword, the PPC cachelines can't overlap with the MC68K series
  258.     cacheline.
  259.  
  260.     HOWEVER, using this keyword fragmentizes the memory really badly
  261.     because of the unuseful unaligned boundary snippets that neither
  262.     can be allocated, nor enter the scratch list.
  263.  
  264.     Even though memory returned from AllocMem() IS aligned to 32 byte
  265.     boundaries, AllocVec'd memory isn't. It is still only long word
  266.     aligned because the first longword of the vector is used to keep
  267.     the size of the allocated memory. This doesn't hurt for the purpose 
  268.     this keyword was invented for; it is, even more, REQUIRED to work
  269.     like this because the vector size should be either in the PPC or
  270.     in the MC68K cache, but not in both.
  271.  
  272.     Due to the heavy fragmentation of memory when using this keyword,
  273.     it is recommended to use it only if absolutely necessary. The
  274.     standard PPC system software deals with the problem of overlapping
  275.     caches correctly so there's by default no need for this keyword.
  276.  
  277.  
  278.     This keyword works quite different from AllocP32. It doesn't use
  279.     "magic cookies" in any way and is written in a way compatible to
  280.     the - rather ugly - layers.library allocation methods (check the
  281.     developer.readme file in this archive for details on this). The
  282.     drawback of this compatibility is the rather high fragmentation,
  283.     it's even higher than without PoolMem. You have been warned!
  284. ______________________________________________________________________________
  285.  
  286. Compatibility:
  287.  
  288.     There are a couple of relatively deep patches of the memory system
  289. that shouldn't be run together with PoolMem:
  290.  
  291. - SetPatch:    The 68040 library which is loaded by this program seems
  292.         to allocate the MMU tables in a strange way incompatible
  293.         to the scratch list of PoolMem. Easy solution: run
  294.         PoolMem after SetPatch.
  295.         This compatibility problems *should* have been fixed with
  296.         the 1.31 option, but hasn't been tested since I've a '030
  297.         on board.
  298. - MemSniff:    (The THOR MungWall replacement)    Patches deep into the memory
  299.         allocation routines, too deep for PoolMem.
  300.  
  301. I guess that's all for now...
  302.  
  303.  
  304. Buggy programs that crash with PoolMem installed:
  305.  
  306. - XiPaint 3.2 (or XMouse, to be precise):
  307.  
  308. The message handling of the mouse driver is broken. After a long debug 
  309. session deep into the night, I found that the crashes were created by the
  310. mouse driver XMouse. It replies messages that are no longer valid and have
  311. been FreeMem()'d before. THIS IS DEFINITELY ILLEGAL AND NOT A POOLMEM PROBLEM.
  312.  
  313. To help you checking other programs as well, I included a tiny patch
  314. "PatchReplyMsg". You shouldn't install it permanently, though, because it
  315. slows down the message system. If, after installation of this patch, a 
  316. program crashes with guru 0x01000001f, THEN THIS PROGRAM HAS THE SAME BUG
  317. AS XIPAINT and replies illegal messages. This will crash your system anyways,
  318. with or without PoolMem. Please sent a bug report to the author, or remove
  319. these programs. As I said, THIS IS NO POOLMEM problem.
  320.  
  321.  
  322. The guru 0x01000013 is rather typical for these programs - they invalidate
  323. the internal scratch list of PoolMem.
  324.  
  325.  
  326. - The Final Odyssey:
  327.  
  328. The memory deallocation routine of this program is buggy. It crashes, too,
  329. with MungWall installed. Since EVERY program that crashes with MungWall is
  330. NOT supposed to be system conformal, I WILL NOT add a workaround for this
  331. problem.
  332.  
  333. Additional node:
  334.  
  335. All PoolMem versions so far contain workarounds for:
  336.  
  337. o) Programs that rely on a "correctly" set zero-condition code of AllocMem()
  338.    ("PixMate")
  339.  
  340. o) the FFS/OFS ACTION_CLOSE bug that does not set the correct result code.
  341. This is currently done by the PoolMem FreeMem() replacement routine. However,
  342. the author of the FFS ("Heinz") has been informed, so it's likely that this
  343. error will be fixed in the next FFS release, probably for the FFS of the
  344. 3.5 workbench.
  345.  
  346. ______________________________________________________________________________
  347.  
  348. Theory of operation:
  349.  
  350.     PoolMem splits all available memory in two blocks: One block is used 
  351. for the small memory snippets (always taken from there), the other block is used
  352. for huge allocations. This partition of the main memory is dynamic, i.e. each
  353. sub-pool can grow and shrink, depending on the memory requirements.
  354.  
  355. The "public/ANY" memory gets a special treatment. PoolMem manages a "scratch"
  356. list for tiny memory blocks taken from there. Instead of taking these tiny
  357. memory blocks always from the main memory, they are taken from this (global,
  358. though) memory pool and put back into this pool if they get freed. A special
  359. garbage collection task cleans this "scratch list" from time to time, or if
  360. it overruns. The main profit is taken from the layers.library, which uses to
  361. allocate tons of tiny snippets and is therefore the main cause for memory
  362. fragmentation.
  363.  
  364. The "chip" memory is treated a bit different. It's also split into two 
  365. distinct memory pools (small and large), but memory from the large pool
  366. is allocated in reverse direction - unless you run PoolMem with the
  367. ChipFwd keyword, of course; this happens for two reasons: First, it
  368. helps to keep the memory defragmentated, so the big pool can't run that
  369. easely into the small pool. Second, it works around a hardware bug of my
  370. computer (the refresh of the high end chip memory in my computer seems to
  371. be a bit buggy - some bits tend to flip if they aren't frequently accessed,
  372. for example by the DMA processor as display memory.)
  373.  
  374. For details about the PatchRAM program, check its readme file. As I said, if
  375. you run PoolMem, you're supposed to run PatchRAM as well. It helps PoolMem
  376. a lot in its job! Future versions of PoolMem will include this patch as
  377. well, but the current version is not yet supposed to be "final" in any
  378. way.
  379.  
  380. _________________________________________________________________________________
  381.  
  382. Additional programs:
  383.  
  384. The PoolMem program is still in a somewhat experimental stage, even though
  385. it's running stable for my system for more than two years now - I won't
  386. expect any serious bugs, though.
  387. However, if you like to see how PoolMem works and if it has any effects, I
  388. provided several extra programs:
  389.  
  390. ShowMem:        Shows the allocated/free memory in a graphical over-
  391.             view. For details, check the ShowMem readme and its
  392.             guide. (Available separately as well)
  393.  
  394. PatchRAM:        Modifies and improves the RAM disk. Shows the correct
  395.             size of the RAM drive, improves the memory allocation
  396.             sheme of it as well. Should be run together with
  397.             PoolMem. For details, check the guide of PatchRAM.
  398.  
  399. FragMeter:        Calculates the fragmentation of your memory. The
  400.             output is given separately for each memory type.
  401.             A 100% fragmentation indicates that all the free
  402.             memory is messed up in tiny blocks of eight bytes
  403.             each (maximal fragmentation).
  404.             A Shannon-type approach is used to measure the
  405.             fragmentation (the algorithm calculates the Shannon
  406.             entropy of the memory blocks with the formula
  407.             sum += log(chunk->mc_Bytes/total)
  408.             If you know a better approach for measuring the
  409.             fragmentation, lemme now. This here seems at least
  410.             reasonable for me as a theoretical physicst... ;-)
  411.             
  412.             This program can be used to test the efficency of
  413.             PoolMem. My measurements indicate that the entropy is
  414.             about halved.
  415.  
  416. MemoryMess:        A program that tries to fragmentate the main memory
  417.             as bad as possible by allocating and freeing memory
  418.             in random order. Can be used together with the 
  419.             FragMeter to measure the efficiency of PoolMem or
  420.             with ShowMem to watch PoolMem at its job. Can be
  421.             canceled safely with ^C (Control-C). Does nothing
  422.             useful except that.
  423.  
  424. PatchReplyMsg:        Useful to find buggy programs, like XiPaint.
  425.             PatchReplyMsg will create a guru 0x0100001f if a
  426.             program attempts to reply an already de-allocated
  427.             message. Don't install it permanently, but use it
  428.             to find the reason for crashes.
  429.  
  430.  
  431. If you've ideas how to improve PoolMem, lemme know....
  432.  
  433. ______________________________________________________________________________
  434.  
  435. Guru meditations thrown by PoolMem:
  436.  
  437. 0x01000013        Scratch entry illegal.
  438.  
  439.             Some program invalidated the internal memory scratch
  440.             list of PoolMem - by overwriting memory that has been
  441.             deallocated before. An (in)famous example is XiPaint.
  442.             Run "PatchReplyMsg" and a debugger (e.g. COP) to check
  443.             for details.
  444.  
  445. 0x0100000f        MemHeader not found.
  446.  
  447.             Some program attempted to free a non-existing block
  448.             of memory. PoolMem (or exec) wasn't able to locate
  449.             the MemHeader.
  450.  
  451.  
  452. 0x01000011        MemHeader insane.
  453.  
  454.             PoolMem found a MemHeader whose number of available
  455.             bytes does not match the size of its pool.
  456.  
  457.  
  458. 0x01000012        Invalid DeleteHeader (internal).
  459.  
  460.             Someone tried to deallocate the "large" memory pool.
  461.             This is an internal guru, shouldn't happen. 
  462.  
  463. 0x01000014        Memory Pools unordered.
  464.  
  465.             Someone changed the order of the memory blocks, the
  466.             large memory block is no longer in front of the
  467.             small memory pool.
  468.  
  469.  
  470. Additionally, PoolMem throws all standard exec guru's - the 1.3x routines
  471. replace the OS functions completely. As a side effect, PoolMem MUST BE RUN
  472. IN FRONT OF OTHER MEMORY TOOLS, especially RUN POOLMEM FIRST, MUNGWALL LATER.
  473.  
  474. ______________________________________________________________________________
  475.  
  476.                         The THOR-Software Licence
  477.  
  478.  
  479. This License applies to the computer programs known as "PoolMem", "ShowMem",
  480. "FragMeter", "MemoryMess" and "ShowMem".
  481. The "Program", below, refers to such program.
  482.  
  483.  
  484. The programs and files in this distribution are freely distributable
  485. under the restrictions stated below, but are also Copyright (c)
  486. Thomas Richter.
  487.  
  488.  
  489. Distribution of the Program by a commercial organization without written
  490. permission from the author to any third party is prohibited if any payment
  491. is made in connection with such distribution, whether directly
  492. (as in payment for a copy of the Program) or indirectly (as in payment
  493. for some service related to the Program, or payment for some product
  494. or service that includes a copy of the Program "without charge";
  495. these are only examples, and not an exhaustive enumeration of prohibited
  496. activities). However, the following methods of distribution involving
  497. payment shall not in and of themselves be a violation of this restriction:
  498.  
  499.  
  500. (i) Posting the Program on a public access information storage and
  501. retrieval service for which a fee is received for retrieving information
  502. (such as an on-line service), provided that the fee is not
  503. content-dependent (i.e., the fee would be the same for retrieving the same
  504. volume of information consisting of random data).
  505.  
  506.  
  507.  
  508. (ii) Distributing the Program on a CD-ROM, provided that the files
  509. containing the Program are reproduced entirely and verbatim on such
  510. CD-ROM, and provided further that all information on such CD-ROM be
  511. redistributable for non-commercial purposes without charge.
  512.  
  513.  
  514.  
  515. Everything in this distribution must be kept together, in original
  516. and unmodified form.
  517.  
  518.  
  519.  
  520.  
  521. Limitations.
  522.  
  523. THE PROGRAM IS PROVIDED TO YOU "AS IS," WITHOUT WARRANTY. THERE IS NO
  524. WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  525. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  526. PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
  527. RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
  528. THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  529. SERVICING, REPAIR OR CORRECTION.
  530.  
  531.  
  532.  
  533. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE ALL FILES CONTAINED IN
  534. THIS ARCHIVE.
  535.  
  536. ______________________________________________________________________________
  537.  
  538. Have fun,
  539.     Thomas        April 1998
  540.