home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / amigalib / d988 / memclear.lha / MemClear / MemClear.doc < prev    next >
Encoding:
Text File  |  1994-04-05  |  14.8 KB  |  352 lines
  1. =======================================================================
  2. ===========================  MemClear V 1.8  ==========================
  3. =======================================================================
  4.  
  5.             MemClear © Copyright 1991-1994 by Ralf Thanner
  6.  
  7.                              Ralf Thanner
  8.                              Ellerstr. 83
  9.                            40227 Düsseldorf
  10.                                GERMANY  
  11.  
  12. =======================================================================
  13. =====================  Disclaimer & Distribution  =====================
  14. =======================================================================
  15.  
  16. Disclaimer
  17. ----------
  18.  
  19. The  executable  and  non-executable parts of this software package may
  20. NOT  be  altered  by  any  means (this includes editing, crunching, and
  21. reverse-engineering), except archiving.  The author is in NO way liable
  22. for  any  changes  made  to  any  part  of the package, or consequences
  23. thereof  as he is in NO way liable for damages or loss of data directly
  24. or indirectly caused by this software.
  25.  
  26. Distribution
  27. ------------
  28.  
  29. Neither fees may  be charged nor  profits may be  made by  distributing
  30. this piece of software. Only a  nominal fee for cost of magnetic  media
  31. may be acceptable. Outside  a single machine  environment, you are  NOT
  32. allowed to reproduce only  some parts of the  package, but you have  to
  33. copy it completely. See this list of contents for verification:
  34.  
  35.              MemClear (dir)
  36.                 MemClear.doc
  37.                 MemClear.doc.info
  38.                 MemClear.guide
  39.                 MemClear.guide.info
  40.                 MemClear
  41.              MemClear.info
  42.  
  43. If  any parts were already missing when you received this package, look
  44. out for another source to get your software in future.
  45.  
  46. =======================================================================
  47. ========================= System Requirements =========================
  48. =======================================================================
  49.  
  50. MemClear works with all Kickstarts, all processors and all memory types
  51. but requires the Arp.library under Kick1.x.
  52.  
  53. =======================================================================
  54. ================================= Author ==============================
  55. =======================================================================
  56.  
  57. MemClear  V1.8  was written by Ralf Thanner using the Devpac assembler,
  58. the  original MemClear idea was suggested from MemClear by John Hodgson
  59. which had some substancial disadvantages.
  60.  
  61. The main disadvantage was that it did not clear anything.  If you don't
  62. believe  me test it, use a monitor to load a file directly into memory,
  63. e.g.   at  location $50000.  Now start Memclear by John Hodgson.  After
  64. Memclear  has finished use a monitor to control your previously choosed
  65. location.  Nothing has changed, no zeros...  funny, isn't it?
  66.  
  67. =======================================================================
  68. ================================ Purpose ==============================
  69. =======================================================================
  70.  
  71. MemClear  clears,  fills  the  unused  memory  chunks.   After clearing
  72. memory,  it prints the amount of cleared bytes in CHIP- and FAST MEMORY
  73. and  the  total  amount  of free bytes.  Keep in mind that MemClear now
  74. clears and fills with blazing speed.
  75.  
  76. Due  to the fact that MemClear will show you the amount of free memory,
  77. how much is in-use and the largest available memory blocks you can also
  78. use  it  instead of the Avail command.  It can also flush all currently
  79. unused  devices,  libraries  and  fonts from memory.  Memclear is pure,
  80. too, and for those reasons a good replacement for Avail.
  81.  
  82. One  of  the  most  powerfull  routines  included  in  MemClear  is the
  83. automatic  Memory  Checker.  Before  MemClear performs an action of any
  84. kind,  the  memory  structures  and  memory  chunks will be checked for
  85. correct  values.  So  if you read the warning, it's a good idea to save
  86. all your current work and re-boot your machine.
  87.  
  88. Although  MemClear  is  a  perfect replacement for Avail and has also a
  89. powerfull  checker  against  memory  failures, its main intention is to
  90. support  programmers  at  their  work,  especially  Assembler   freaks.
  91. Clearing  memory  without  destroying  the  nodes  makes  debugging and
  92. programming (e.g. resident stuff) much easier in many cases.
  93.  
  94. =======================================================================
  95. ================================ Usage ================================
  96. =======================================================================
  97.  
  98.     MemClear cannot be started from Workbench, it is a Shell tool!
  99.  
  100.  
  101. The following commands are supported:
  102.  
  103.  
  104.         "AVAIL"   - Displays the  free memory  without  clearing. Avail
  105.                     does  NOT count the  real free bytes. It is just an
  106.                     avail clone.
  107.  
  108.                     NOTE: if you have 'DynamiCache' in the background
  109.                           the amount of  free bytes  shown may differ
  110.                           from the amount of memory you have inbuilt.
  111.  
  112.  
  113.         "FLUSH"   - Flushing all  currently  unused  devices, libraries
  114.                     and fonts from memory.
  115.                     After flushing  memory MemClear will print how much
  116.                     more memory is free now.
  117.  
  118.  
  119.         "NoClear" - This  option is useful if you just want your memory
  120.                     flushed without clearing.Especially if you're using
  121.                     DynamiCache, this opt  will be very  useful in case
  122.                     you just want to flush unused devices, fonts etc.
  123.  
  124.  
  125.         "NoWarn"  - This option switches off the obligatory mem checker
  126.                     and  should  only be used if you are either running
  127.                     OS3.x  (performs also a memory sanity check)  or if
  128.                     you really know what you are doing.
  129.  
  130.  
  131.         "QUIET"   - All actions will be performed silent.
  132.  
  133.  
  134. Following options are allowed:
  135.  
  136.  
  137.         "F"       - Fills only free fast-memory.
  138.  
  139.         "C"       - Fills only free chip-memory.
  140.  
  141.  
  142. If  you don't want the memory cleared, but rather be filled use a 'FILL
  143. VALUE' which is defined this way:
  144.  
  145.  
  146.         "-$FE"    - Fills memory with $fe instead of zeros. All
  147.                     hexadecimals  are allowed. One  single  hex
  148.                     value, e.g. '-$b' will be expanded to '$bb'. 
  149.  
  150.         "-A"      - Fills memory with  choosen  character. This
  151.                     option IS case sensitive.
  152.  
  153.  
  154. If  MemClear is invoked without any option it will simply fill the free
  155. memory  with  zeros  and  print the (real) free amount of memory.  Real
  156. free  memory  means  that  this  is  not necessarily the amount of free
  157. memory the system has stored in its memheader structure, but rather the
  158. amount of bytes encountered in the memory chunks.
  159.  
  160. =======================================================================
  161. =============================  Examples  ==============================
  162. =======================================================================
  163.  
  164. MemClear F
  165.  
  166. clears  the  fast-mem  area with zeros and won't touch a single byte in
  167. chip memory.
  168.  
  169.  
  170. MemClear FLUSH C -$ff
  171.  
  172. first  flushs unused stuff from memory and then fills all free chip-mem
  173. with the hex-value '$ff' leaving the fast-mem area untouched.
  174.  
  175.  
  176. MemClear AVAIL
  177.  
  178. displays  complete  memory  statistics, comparable to Commodore's Avail
  179. command without filling, clearing or flushing.
  180.  
  181.  
  182. MemClear FLUSH NOCLEAR
  183.  
  184. flushs  unused  system resources, such as fonts, libraries, and devices
  185. from memory without filling or clearing. You may configure a "MemFlush"
  186. button  or  menu  inside DirectoryOpus using this template. That's very
  187. useful if you're running out of memory.
  188.  
  189. =======================================================================
  190. ============================  Error Codes  ============================
  191. =======================================================================
  192.  
  193. MemClear  will  return  an error code if something went wrong.  This is
  194. very useful for 'FAILAT' and 'IF' commands in batch skripts.
  195.  
  196.    RETURN WARN  (05) for zero bytes gained with FLUSH.
  197.    RETURN ERROR (10) for all internal errors (e.g. no arp.lib).
  198.    RETURN FAIL  (20) for an error in the memory structure.
  199.  
  200.  
  201. Example:
  202. --------
  203.  
  204.         FAILAT  5
  205.          MemClear FLUSH QUIET            ; will flush memory without
  206.                                          ; printing any text...
  207.        IF WARN
  208.         TYPE "flush_brachte_nichts.txt"  ; "flush_wasnt_successfull"-)
  209.        ELSE
  210.  
  211. =======================================================================
  212. ==========================  Memory Checker  ===========================
  213. =======================================================================
  214.  
  215. MemClear  performs  two  different  structure  tests.  The  first scans
  216. through  all  memory  nodes  checking  them  against correct values and
  217. boundaries.   When  something  went  wrong the following  message  will be
  218. printed  " Warning!  Memory List is corrupted at:  $'address' ".  If you
  219. read  this  SAVE  EVERYTHING  IMMEDIATELY, because sooner or later your
  220. Amiga  will  crash!   There are some bad written programs which destroy
  221. parts  of  the  internal  memory  lists.   These  programs, like an old
  222. version  of  decrunch.library  did,  WILL  cause  a  crash if memory is
  223. flushed  or cleared, even if you have already 'quitted' them!  There is
  224. no  guarantee that the printed address is the location where the memory list
  225. is corrupted, but you have a good chance for correctness.
  226.  
  227. The second test just checks if the amount of 'real' free bytes, counted
  228. by  MemClear  while  scanning  through all memory nodes, is the same as
  229. stored  in  Execbase.   When  this  error message appears there is also
  230. something  wrong  with  your  system but normally it won't crash in the
  231. next seconds.
  232.  
  233. =======================================================================
  234. ======================  Speed comparison table  =======================
  235. =======================================================================
  236.  
  237.         complete memory clearing / filling using MemClear v1.8
  238.  
  239.  
  240. A500,  MC68000 7Mhz, 512kb Chip + 2MB Ranger Mem   :       2,9 MB/sec
  241.  
  242. A1000, MC68010 7MHz, 512kb Chip + 4MB Fast Mem     :       3,1 MB/sec
  243.  
  244. A3000, MC68030 25MHz,  2MB Chip + 4MB Fast Mem     :       8,4 MB/sec
  245.  
  246.  
  247. all  tests  performed  under  realistic circumstances, that means after
  248. booting fully-featured Workbench from HD.
  249.  
  250. =======================================================================
  251. ===============================  ThanX  ===============================
  252. =======================================================================
  253.  
  254.        Timm Müller   - For help with  documentation/guidefile  and some
  255.                        guide on the way to good readable and structured
  256.                        sources.
  257.                        
  258.        Olaf Barthel  - For supporting  me with the  original version of
  259.                        Memclear done by John Hodgson.
  260.  
  261.        Martin Berndt - For  telling  me  that MemClear is really useful
  262.                        because it helped programming and  debugging the
  263.                        PICASSO  II graphics card software. Sometimes it
  264.                        is really nice to get such a good response.
  265.                        Also thanx for finding the  DynamiCache 'bug'!-)
  266.  
  267. =======================================================================
  268. ==============================  History  ==============================
  269. =======================================================================
  270.  
  271. -----  V1.8  ----------------------------------------------------------
  272.  
  273.        - clear and fill algorythm now fits perfectly into the 680x0
  274.          cache.
  275.        - the memory checker is much better now and should be able to
  276.          handle all kind of structure errors.
  277.        - MemClear will now return  'Error Codes'  for usage in batch
  278.          skripts.
  279.  
  280. -----  V1.7  ----------------------------------------------------------
  281.  
  282.        - added the check for 'real' free bytes and the value stored
  283.          in Execbase. With this routine implemented earlier I would
  284.          have found the reason for  mysterious  crashes after using
  285.          'decrunch.library' much earlier;-(
  286.        - if you use 'FLUSH' all available memory will be printed.
  287.        - after flushing the memory gain will be shown.
  288.        - MemClear is now using official 'cli-readargs' routines,
  289.          instead of my own home brewn interface.
  290.        - included fill-pattern routine in normal clear routine.
  291.        - rewrote clear; clears/fills now about 3.1MB/sec on MC68010!
  292.        - command 'avail' shows now REALLY everything  Avail does;-)
  293.  
  294. -----  V1.6  ----------------------------------------------------------
  295.  
  296.        - implemented  'FLUSH'  option.
  297.        - fixed small (and silly) bug in the 'byte counting' routine.
  298.  
  299. -----  V1.5  ----------------------------------------------------------
  300.  
  301.        - fixed small bug in the cli-interface.
  302.        - MemClear is now PURE.
  303.  
  304. -----  V1.4  ----------------------------------------------------------
  305.  
  306.        - added choice which mem-area should be cleared.
  307.        - improved the cli-interface  (e.g.  'f -a' and  '-a f' are now
  308.          both recognized).
  309.        - fixed some troubles with MC68040.
  310.  
  311. -----  V1.3  ----------------------------------------------------------
  312.  
  313.        - code completely rewritten.
  314.        - new clear algo which fits now perfect into the 68020/30 cache
  315.          and also takes advantage of the 68010 prefetch!-) Clear needs
  316.          now 1 second for 2.4MB on 68010 (average value, may differ).
  317.        - Blitter won't be used to clear chip-mem anymore, due  to  the
  318.          fact that the blitter in the  A3000 or  A4000  is slower than
  319.          the  prozessor  (MC68040 speed rulez!).  
  320.        - added different  fill-patterns. This  one uses a  real simple
  321.          and 'slow' clear algo but who cares!?-)
  322.  
  323. -----  V1.2  ----------------------------------------------------------
  324.  
  325.        - Added the 'free mem' text in instructions.
  326.        - Fixed the 'print-txt' routine.
  327.  
  328. -----  V1.1  ----------------------------------------------------------
  329.  
  330.        - Removed the  FAST OPTION, since it's fast enough without this
  331.          nasty method.
  332.        - Clears now $C00000 mem on A500.
  333.        - Added the  'total free bytes' for a complete overview of free
  334.          memory, MemClear shows now almost everything AVAIL does.
  335.  
  336. -----  V1.0  ----------------------------------------------------------
  337.  
  338.        - Improved clear algorithm, needs now less  than two seconds
  339.          for 2.5 MB.
  340.        - added special 'FAST OPTION' which is a pure hardware hack.
  341.          (only usefull when you have more than 5 MB; disables all.)
  342.  
  343. -----  V0.9  ----------------------------------------------------------
  344.  
  345.        - Thought, that this is the final version... No bug reports.
  346.        - Works fine, but clears slow (about 4 seconds for 2.5 MB).
  347.  
  348. =======================================================================
  349. ===========================  MemClear V 1.8  ==========================
  350. =======================================================================
  351. EoD
  352.