home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / dynamite / DynManText < prev    next >
Text File  |  1995-08-01  |  31KB  |  1,145 lines
  1.                     _
  2.                    / \         ___   ___   _____   ·  /_  __
  3.                   /   ) /   / /   ) /   ) /  /  ) /  /   /__)
  4.                  /___/ (___/ /   ( (___( /  /  ( (_ (_  (___
  5.                       ____/
  6.  
  7.                               Programmer's Guide
  8.  
  9.  
  10.  
  11.                                   Straylight
  12.  
  13.                   16 Portland Street, Royal Leamington Spa,
  14.                             Warwickshire, CV32 5HE
  15.  
  16.                     Telephone and facsimile: 01926 452639
  17.                     Email:  strylght@strylght.demon.co.uk
  18. _____________________________________________________________________________
  19.  
  20.         © 1995 Straylight
  21.  
  22.         This documentation refers to Dynamite module version 1.15
  23.  
  24.         The Dynamite software and accompanying documentation are to be
  25.         considered as `Freeware' -- they may be reproduced and distributed on
  26.         condition that they are not altered in any way and no profit is made
  27.         by so doing.  You may supply the Dynamite module with any software
  28.         which uses it, including software for which a profit is made.
  29.  
  30.         Because the program is licensed free of charge, there is no warranty
  31.         for the program, to the extent permitted by applicable law.  Except
  32.         when otherwise stated in writing the copyright holders and/or other
  33.         parties provide the program `as is' without warranty of any kind,
  34.         either expressed or implied, including, but not limited to, the
  35.         implied warranties of merchantability and fitness for a particular
  36.         purpose.  The entire risk as to the quality and performance of the
  37.         program is with you.  Should the program prove defective, you assume
  38.         the cost of all necessary servicing, repair or correction.
  39.  
  40.         The product described in this documentation is the subject of
  41.         continual development and, while all efforts are taken to ensure
  42.         that the information given is correct, Straylight cannot accept any
  43.         liability for loss or damage resulting from the use or misuse of this
  44.         product.
  45.  
  46. Trademarks
  47.  
  48.         Acorn, Archimedes and RISC PC are trademarks of Acorn Computers Ltd.
  49.         ARM is a trademark of Advanced RISC Machines Ltd.
  50.  
  51.         All other trademarks acknowledged.
  52. _____________________________________________________________________________
  53.  
  54. Dynamite overview
  55.  
  56.  
  57. What does Dynamite do?
  58.  
  59.         One of the greatest problems facing module writers is that of
  60.         allocating memory.  Although the Relocatable Module Area has been
  61.         provided to allow modules to allocate workspace, its design causes
  62.         it to fragment over a period of time.
  63.  
  64.         Programmers have been aware of this problem for a long time, and
  65.         several have started to use the System Sprite Area as an alternative
  66.         source of memory, since it does not suffer from fragmentation in the
  67.         same way as the RMA.
  68.  
  69.         Acorn have finally addressed this difficulty and enabled modules
  70.         running under RISC OS 3.5 or later to create their own dynamic areas,
  71.         which they can then manage themselves, for example, by implementing a
  72.         shifting heap similar to that used by most applications.
  73.         Unfortunately this solution is not available to programs required to
  74.         run on machines earlier than the RISC PC.
  75.  
  76.         Dynamite is a small module which provides a solution to the problem
  77.         of memory allocation without causing fragmentation of the RMA,
  78.         abusing the Sprite area, or being specific to any particular
  79.         operating system versions.  This means that code which uses Dynamite
  80.         should be able to run on any version of RISC OS.
  81.  
  82.         Running under RISC OS 3.5 or later, Dynamite creates its own dynamic
  83.         area and implements within it a shifting heap which is compacted over
  84.         a period of time by a WIMP task.
  85.  
  86.         Under earlier versions of RISC OS, Dynamite shuffles the memory map
  87.         to create its own `dynamic area', and implements within it a
  88.         shifting heap as before.
  89.  
  90.         The interface to the Dynamite memory manager is identical, whether or
  91.         not a real dynamic area is used.  Since blocks are always allocated
  92.         within Dynamite's special area of memory, clients which require
  93.         blocks of memory and can cope with them being moved around can now
  94.         obtain them without fragmenting the RMA.
  95.  
  96.  
  97. How Dynamite works
  98.  
  99.   Operation under RISC OS 3.5 or later
  100.  
  101.         Dynamite's operation under RISC OS 3.5 is fairly simple -- the new
  102.         facilities provided by OS_DynamicArea are used to create and resize
  103.         the heap as required.
  104.  
  105.   Operation under RISC OS versions prior to 3.5
  106.  
  107.         Since early versions of RISC OS do not provide calls for creating
  108.         dynamic areas, Dynamite takes matters into its own hands.  It uses
  109.         the area of logical memory at the end of the System Sprite area (up
  110.         to &01800000) to build its heap.
  111.  
  112.         Normally, the System Sprite Area is layed out as shown below:
  113.  
  114.                         [Picture: DynManDocs.Diag_1/1]
  115.  
  116.         Only the shaded area used by the system sprites actually has physical
  117.         memory pages associated with it.
  118.  
  119.         Dynamite creates its area at the other end of the System Sprite Area,
  120.         from 24M downwards, as shown overleaf.
  121.  
  122.                         [Picture: DynManDocs.Diag_1/2]
  123.  
  124.         Operating system routines are intercepted to ensure that Dynamite's
  125.         maintenance of this area does not affect the normal operation of the
  126.         kernel's memory management.
  127.  
  128.         It should be noted that because of this method of implementation,
  129.         there is a limit of 4M (assuming there are no System Sprites) on the
  130.         size of Dynamite's heap.  The RMA also has a limit of 4M, and this
  131.         is rarely exceeded, so this is unlikely to cause a problem in
  132.         practice.
  133.  
  134.         It should be noted that the Task Manager will show the size of the
  135.         Sprite area including Dynamite's area.  However, OS_ReadDynamicArea
  136.         will return only the amount occupied by the System Sprites, allowing
  137.         programs which use sprites to store their data to work as before.
  138.         OS_ChangeDynamicArea will continue to work as before; only the area
  139.         containing the System Sprites will change in size.
  140.  
  141.         Warning: To the best of our knowledge, there are no other programs
  142.         which use the area of memory at the end of the Sprite area.  If
  143.         similar modules appear, there are likely to be severe compatibility
  144.         problems.  It is for this reason that we have decided to publish the
  145.         interface to Dynamite.
  146. _____________________________________________________________________________
  147.  
  148. Using Dynamite
  149.  
  150.  
  151. Who can use Dynamite?
  152.  
  153.         Straylight have decided to make this module `freeware'.  It remains
  154.         at all times Copyright © 1994 Straylight, however it may be
  155.         distributed with products which wish to use it, whether or not they
  156.         are commercial.  No charge may be made for Dynamite specifically,
  157.         and the module must not be altered in any way.
  158.  
  159.         All products distributed with Dynamite must state in the main
  160.         documentation that Dynamite is © 1994 Straylight.
  161.  
  162.  
  163. Loading Dynamite
  164.  
  165.         Dynamite should normally be loaded from an Obey file in the following
  166.         way:
  167.  
  168.                 RMEnsure Dynamite 0.00 RMRun <My$Dir>.Dynamite
  169.                 RMEnsure Dynamite 1.11 Error 0 Dynamite module is too old
  170.  
  171.         It is important to note that the Dynamite module must be RMRun, not
  172.         just RMLoaded -- this will ensure that the Dynamite WIMP task is
  173.         started correctly.
  174. _____________________________________________________________________________
  175.  
  176. About the Dynamite heap
  177.  
  178.  
  179. Shifting heaps
  180.  
  181.         Dynamite allocates blocks from a shifting heap.  This means that
  182.         blocks allocated from the heap will be moved around in order to
  183.         close up any gaps created by freeing blocks.  In a normal heap, for
  184.         example that implemented by OS_Heap or the C library's malloc
  185.         function, the free memory in the heap can become fragmented