home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / memmanagement / dynamite / dynamite_2 / DynManText < prev    next >
Text File  |  1995-09-19  |  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.17
  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.  For
  186.         example, consider a heap from which 3 blocks have been allocated:
  187.  
  188.                         [Picture: DynManDocs.Diag_3/1]
  189.  
  190.         The lower area of the heap has been allocated, but there is a chunk
  191.         of free memory at the end, which can be claimed.  If block 2 is now
  192.         freed, the heap would look like this:
  193.  
  194.                         [Picture: DynManDocs.Diag_3/2]
  195.  
  196.         There are now two free areas which memory may be allocated, but since
  197.         they are not contiguous, the size of the largest block which can be
  198.         allocated is dictated by the size of the largest free area.  If the
  199.         free space could be coalesced in some way, then obviously all the
  200.         free space in the heap is available for allocation.
  201.  
  202.         Clearly, the only way to gather these free areas together is by
  203.         moving the allocated blocks.  It is this property which defines the
  204.         shifting heap.  The problem with a shifting heap is that the blocks
  205.         allocated in it can move whenever free space is generated within the
  206.         heap.  Programs making use of such a memory manager must be able to
  207.         cope with this.
  208.  
  209.  
  210. Dynamite's memory manager
  211.  
  212.         Dynamite implements a shifting heap within its dynamic area.  As a
  213.         result, programs making use of Dynamite must be able to deal with
  214.         their blocks of memory being moved.  Since Dynamite may be used by
  215.         multiple clients, each must be aware that its blocks may be shifted
  216.         while it does not have control of the processor.  For each block you
  217.         allocate, you must tell Dynamite the address of your pointer to the
  218.         block.  This pointer is called the block's anchor pointer.  This is
  219.         so that Dynamite can update your anchor when the block moves.  Note
  220.         that you should not put anchors into application memory, since
  221.         Dynamite may have to update them while your application is paged out.
  222.         To make this easier, Dynamite allows you to allocate anchors from the
  223.         RMA very easily.  You can then store the address of the anchor in
  224.         your own memory.
  225.  
  226.         You should always address a Dynamite block through its anchor
  227.         pointer, rather than taking copies of the block address.  If you
  228.         don't do this, Dynamite will correctly update the block's anchor
  229.         should the block move, leaving any other copies of the address
  230.         unchanged.  Of course, you can assume that pointers remain valid
  231.         while you have control, but e.g.  calling Wimp_Poll may cause them to
  232.         be invalidated, since Dynamite uses idle events to compact the heap.
  233.  
  234.  
  235. Using Dynamite from interrupt routines
  236.  
  237.         Most Dynamite routines are not re-entrant, so you should request a
  238.         callback before using them.  You must also take into account that the
  239.         foreground application may have pointers to Dynamite blocks tem
  240.         porarily in registers or on the stack etc., which you should ensure
  241.         remain valid.  To assist you in this, Dynamite will normally only
  242.         move blocks which you explicitly resize.  However, if enough memory
  243.         is not available, Dynamite will attempt to compact the heap.  You
  244.         must therefore disable this using the SWI Dynamite_Lock.
  245.  
  246.         As long as the foreground task is guaranteed to not have access to
  247.         blocks used by your callback routine, or it has been written to cope
  248.         with this, then you will not have any problems.
  249.  
  250. Using Dynamite from SWIs
  251.  
  252.         You should take careful note of the points raised in the previous
  253.         section when writing SWI handlers which use Dynamite, since your SWI
  254.         may well be called from a callback routine.
  255.  
  256.  
  257. Using Dynamite from command line applications
  258.  
  259.         You must be aware that the user may want to run your command line
  260.         application within a TaskWindow.  This may cause your application to
  261.         lose control of the processor at arbitrary points within your
  262.         program, during which time, the rest of the desktop is active.  This
  263.         means that other applications may cause blocks to move within the
  264.         Dynamite heap -- in particular, Dynamite may be compacting the heap
  265.         during this time.  To prevent this from happening, you should lock
  266.         the heap while you are accessing Dynamite blocks and unlock it again
  267.         when you have finished, using the relevant SWIs.
  268.  
  269.  
  270. The Dynamite relocation stack
  271.  
  272.         To help you keep track of blocks when they move, you can save
  273.         pointers on a special stack.  When you load the pointers back, they
  274.         will have been relocated so that they still point at the same data
  275.         object, even if it was within a Dynamite block which has been moved.
  276.  
  277.  
  278. Block IDs
  279.  
  280.         When you allocate a block using Dynamite_Alloc, you can specify a
  281.         block ID to associate with it.  This can be any 32-bit value you
  282.         like, although it should be something unlikely to conflict with
  283.         other client's IDs, e.g.:
  284.  
  285.         * A module's base address
  286.  
  287.         * An application's task handle or start time
  288.  
  289.         If you want your program to have multiple IDs, you could divide the
  290.         ID value into a `magic' field (say 24 bits of module base address)
  291.         and an index number.
  292.  
  293.         Later, you can free all blocks with a particular ID.  This is useful
  294.         when you want to free all the blocks associated with a particular
  295.         object when that object is destroyed.  For example, during
  296.         development of a module, you could free all its Dynamite blocks in
  297.         the finalisation code.
  298.  
  299.  
  300. Compaction of the Dynamite heap
  301.  
  302.         The Dynamite module has a WIMP task which will partially tidy the
  303.         heap while the processor is idle.  This means that the process of
  304.         removing free space from the heap is distributed over a period of
  305.         time, and will probably not be noticeable in average use.
  306.  
  307.         If you are writing a program which will not multitask, you should
  308.         perform this tidying yourself from time to time, using the
  309.         appropriate Dynamite SWIs.
  310. _____________________________________________________________________________
  311.  
  312. SWI calls
  313.  
  314.  
  315. Standard features
  316.  
  317.         Dynamite SWIs obey the following conventions:
  318.  
  319.         * Arguments are passed in registers, starting from R0.  Return values
  320.          are also given in registers.
  321.  
  322.         * All registers not explicitly used to return results are preserved.
  323.  
  324.         * On exit, the V flag is used to indicate an error status.  The carry
  325.           flag may be used to return information as well, although this is
  326.           documented with the appropriate SWIs when it happens.  In all other
  327.           cases, the C, N and Z flags are preserved when there is no error.
  328.  
  329.  
  330. Dynamite_Alloc (SWI &4A3C0)
  331.  
  332.         Allocates a block of memory from the Dynamite heap
  333.  
  334. On entry
  335.  
  336.         R0 = address of block anchor
  337.         R1 = size of block to allocate, in bytes
  338.         R2 = block ID, or 0 for none
  339.  
  340. On exit
  341.  
  342.         R0, R1 preserved
  343.         R2 = address of allocated block
  344.  
  345. Interrupts
  346.  
  347.         Interrupt status is undefined
  348.         Fast interrupts are enabled
  349.  
  350. Processor mode
  351.  
  352.         Processor is in SVC mode
  353.  
  354. Re-entrancy
  355.  
  356.         SWI is not re-entrant
  357.  
  358. Use
  359.  
  360.         This SWI allocates a block from the Dynamite heap.
  361.  
  362.         This SWI may cause blocks to move within the Dynamite heap.
  363.  
  364. Related SWIs
  365.  
  366.         * Dynamite_Free
  367.  
  368.  
  369. Dynamite_Free (SWI &4A3C1)
  370.  
  371.         Frees a Dynamite block, releasing the memory it used
  372.  
  373. On entry
  374.  
  375.         R0 = pointer to anchor of block to be freed
  376.  
  377. On exit
  378.  
  379.         --
  380.  
  381. Interrupts
  382.  
  383.         Interrupt status is not defined
  384.         Fast interrupts are enabled
  385.  
  386. Processor mode
  387.  
  388.         Processor is in SVC mode
  389.  
  390. Re-entrancy
  391.  
  392.         SWI is not re-entrant
  393.  
  394. Use
  395.  
  396.         This SWI will free a block in the Dynamite heap, releasing the memory
  397.         it used for later reallocation.  The free memory will later be
  398.         returned to the operating system during compaction.
  399.  
  400. Related SWIs
  401.  
  402.         * Dynamite_Alloc
  403.         * Dynamite_FreeWithID
  404.  
  405.  
  406. Dynamite_FreeWithID (SWI &4A3C2)
  407.  
  408.         Frees all blocks with a given block ID
  409.  
  410. On entry
  411.  
  412.         R0 = block ID (must be non-zero)
  413.  
  414. On exit
  415.  
  416.         --
  417.  
  418. Interrupts
  419.  
  420.         Interrupt status is not defined
  421.         Fast interrupts are enabled
  422.  
  423. Processor mode
  424.  
  425.         Processor is in SVC mode
  426.  
  427. Re-entrancy
  428.  
  429.         SWI is not re-entrant
  430.  
  431. Use
  432.  
  433.         This SWI will free all blocks which have a specified block ID.
  434.  
  435. Related SWIs
  436.  
  437.         * Dynamite_Free
  438.  
  439.  
  440. Dynamite_BlockInfo (SWI &4A3C3)
  441.  
  442.         Returns information about a Dynamite block
  443.  
  444. On entry
  445.  
  446.         R0 = address of block anchor
  447.  
  448. On exit
  449.  
  450.         R0 preserved
  451.         R1 = address of block
  452.         R2 = current size of block, in bytes
  453.         R3 = block ID, as passed to Dynamite_Alloc
  454.  
  455. Interrupts
  456.  
  457.         Interrupt status is not defined
  458.         Fast interrupts are enabled
  459.  
  460. Processor mode
  461.  
  462.         Processor is in SVC mode
  463.  
  464. Re-entrancy
  465.  
  466.         SWI is re-entrant
  467.  
  468. Use
  469.  
  470.         This SWI returns various pieces of information about a Dynamite
  471.         block.
  472.  
  473.         The size in R2 is the byte aligned size given to Dynamite_Alloc when
  474.         the block was created, possibly altered subsequently by
  475.         Dynamite_Resize or Dynamite_MidExtend.
  476.  
  477. Related SWIs
  478.  
  479.         None
  480.  
  481.  
  482. Dynamite_ChangeID (SWI &4A3C4)
  483.  
  484.         Changes the ID of a given block, or all blocks with a given ID
  485.  
  486. On entry
  487.  
  488.         R0 = address of anchor for block, or 0 for all blocks
  489.         R1 = new ID
  490.         R2 = old ID (if R0 = 0)
  491.  
  492. On exit
  493.  
  494.         --
  495.  
  496. Interrupts
  497.  
  498.         Interrupt status is not defined
  499.         Fast interrupts are enabled
  500.  
  501. Processor mode
  502.  
  503.         Processor is in SVC mode
  504.         Re-entrancy
  505.         SWI is not re-entrant
  506.  
  507. Use
  508.  
  509.         This SWI will change the ID of the block whose anchor is passed in
  510.         R0, or the ID of all the blocks which have the ID passed in R2,
  511.         if R0 = 0.
  512.  
  513. Related SWIs
  514.  
  515.         None
  516.  
  517.  
  518. Dynamite_Resize (SWI &4A3C5)
  519.  
  520.         Alters the size of a Dynamite block
  521.  
  522. On entry
  523.         R0 = address of block anchor
  524.         R1 = new size of block, in bytes
  525.  
  526. On exit
  527.  
  528.         R0 preserved
  529.         R1 = address of block, which may have moved
  530.  
  531. Interrupts
  532.  
  533.         Interrupt status is not defined
  534.         Fast interrupts are enabled
  535.  
  536. Processor mode
  537.  
  538.         Processor is in SVC mode
  539.  
  540. Re-entrancy
  541.  
  542.         SWI is not re-entrant
  543.  
  544. Use
  545.  
  546.         This SWI will change a block's size.  The exact behaviour of this
  547.         routine depends on whether the new size is greater than or less than
  548.         the old size.  If you are reducing the size of a block, bytes will be
  549.         removed from the end.  Out-of-memory errors will not be returned.
  550.  
  551.         If you are extending a block, bytes are added at the end.  An out-of-
  552.         memory error may be returned if there is not enough memory to extend
  553.         the block.
  554.  
  555.         This SWI may cause blocks to move within the Dynamite heap.
  556.  
  557. Related SWIs
  558.  
  559.         * Dynamite_MidExtend
  560.  
  561.  
  562. Dynamite_MidExtend (SWI &4A3C6)
  563.  
  564.         Inserts or deletes bytes at a given offset within a block
  565.  
  566. On entry
  567.  
  568.         R0 = address of block anchor
  569.         R1 = offset within block to add or remove bytes
  570.         R2 = signed number of bytes to add
  571.  
  572. On exit
  573.  
  574.         R0 preserved
  575.         R1 = address of block, which may have moved
  576.  
  577. Interrupts
  578.  
  579.         Interrupt status is not defined
  580.         Fast interrupts are enabled
  581.  
  582. Processor mode
  583.  
  584.         Processor is in SVC mode
  585.  
  586. Re-entrancy
  587.  
  588.         SWI is not re-entrant
  589.  
  590. Use
  591.  
  592.         This call will, depending on whether R2 is positive or negative,
  593.         insert or remove bytes from a Dynamite block starting at the offset
  594.         given in R1.  This may of course cause the block's size to change.
  595.         Always after a call to Dynamite_MidExtend, the data that was
  596.         previously at offset R1 is moved to offset R1+R2.
  597.  
  598.         The diagrams below show the effects of inserting or removing bytes
  599.         from a block:
  600.  
  601.                         [Picture: DynManDocs.Diag_4/1]
  602.  
  603.         Diagram 1: Inserting bytes
  604.  
  605.                         [Picture: DynManDocs.Diag_4/2]
  606.  
  607.         Diagram 2: Removing bytes
  608.  
  609.         This SWI may cause blocks to move within the Dynamite heap.
  610.  
  611. Related SWIs
  612.  
  613.         * Dynamite_Resize
  614.  
  615.  
  616. Dynamite_Save (SWI &4A3C7)
  617.  
  618.         Saves some registers on Dynamite's relocation stack
  619.  
  620. On entry
  621.  
  622.         R0 = bit mask of registers to save
  623.         Other registers as described below
  624.  
  625. On exit
  626.  
  627.         --
  628.  
  629. Interrupts
  630.  
  631.         Interrupt status is not defined
  632.         Fast interrupts are enabled
  633.  
  634. Processor mode
  635.  
  636.         Processor is in SVC mode
  637.  
  638. Re-entrancy
  639.  
  640.         SWI is not re-entrant
  641.  
  642. Use
  643.  
  644.         This SWI will save the registers specified in R0 on Dynamite's
  645.         relocation stack.  R0 should contain a bit set for each register
  646.         that you want saved -- i.e.  bit 1 set to save R1, etc.
  647.  
  648.         You cannot usefully save R9-R15 or R0, so the corresponding bits of
  649.         R0 should not be set on entry.
  650.  
  651.         The stack is ascending, and follows the normal ARM rules for
  652.         ascending stacks.  Hence if you save R1-R7 on the stack, the saved
  653.         R7 will be the first register to be removed.
  654.  
  655.         The upper two bytes of R0 are ignored by this SWI.  Therefore R0 on
  656.         entry can actually contain an STM instruction specifying the required
  657.         registers.
  658.  
  659. Related SWIs
  660.  
  661.         * Dynamite_Load
  662.  
  663.  
  664. Dynamite_Load (SWI &4A3C8)
  665.  
  666.         Restores registers from Dynamite's relocation stack
  667.  
  668. On entry
  669.  
  670.         R0 = bit mask of registers to load
  671.  
  672. On exit
  673.  
  674.         As described below
  675.  
  676. Interrupts
  677.  
  678.         Interrupt status is not defined
  679.         Fast interrupts are enabled
  680.  
  681. Processor mode
  682.  
  683.         Processor is in SVC mode
  684.  
  685. Re-entrancy
  686.  
  687.         SWI is not re-entrant
  688.  
  689. Use
  690.  
  691.         This SWI will load the registers specified in R0 from Dynamite's
  692.         relocation stack.  R0 should contain a bit set for each register that
  693.         you want loaded -- i.e.  bit 1 set to load R1, etc.
  694.  
  695.         You must not load R9-R15, so the corresponding bits of R0 should not
  696.         be set on entry.
  697.  
  698.         The stack is ascending, and follows the normal ARM rules for
  699.         ascending stacks.  Hence if you save R1-R7 on the stack, the saved
  700.         R7 will be the first register to be removed.
  701.  
  702.         The upper two bytes of R0 are ignored by this SWI.  Therefore R0 on
  703.         entry can actually contain an LDM instruction specifying the required
  704.         registers.
  705.  
  706. Related SWIs
  707.  
  708.         * Dynamite_Save
  709.  
  710.  
  711. Dynamite_Reduce (SWI &4A3C9)
  712.  
  713.         Performs a partial compaction of the Dynamite heap
  714.  
  715. On entry
  716.  
  717.         --
  718.  
  719. On exit
  720.  
  721.         C set if no compaction performed, clear otherwise
  722.  
  723. Interrupts
  724.  
  725.         Interrupt status is not defined
  726.         Fast interrupts are enabled
  727.  
  728. Processor mode
  729.  
  730.         Processor is in SVC mode
  731.  
  732. Re-entrancy
  733.  
  734.         SWI is not re-entrant
  735.  
  736. Use
  737.  
  738.         This call will partially compact Dynamite's heap.  It may fail
  739.         (returning C set) if either the heap is already compact, or if the
  740.         heap is locked.  Calling Dynamite_Reduce in a loop until it returns
  741.         with C set will result in the heap being fully compacted.
  742.  
  743.         This SWI may cause blocks to move within the Dynamite heap.
  744.  
  745. Related SWIs
  746.  
  747.         * Dynamite_Compact
  748.  
  749.  
  750. Dynamite_Compact (SWI &4A3CA)
  751.  
  752.         Fully compacts the Dynamite heap
  753.  
  754. On entry
  755.  
  756.         --
  757.  
  758. On exit
  759.  
  760.         C set if no action performed, clear otherwise
  761.  
  762. Interrupts
  763.  
  764.         Interrupt status is not defined
  765.         Fast interrupts are enabled
  766.  
  767. Processor mode
  768.  
  769.         Processor is in SVC mode
  770.  
  771. Re-entrancy
  772.  
  773.         SWI is not re-entrant
  774.  
  775. Use
  776.  
  777.         This routine will fully compact Dynamite's heap, returning any free
  778.         space to the operating system.  It may fail (returning C set) either
  779.         if the heap is already compact, or if the heap is locked.
  780.  
  781.         This SWI may cause blocks to move within the Dynamite heap.
  782.  
  783. Related SWIs
  784.  
  785.         * Dynamite_Reduce
  786.  
  787.  
  788. Dynamite_Lock (SWI &4A3CB)
  789.  
  790.         Locks the heap, preventing blocks from moving
  791.  
  792. On entry
  793.  
  794.         --
  795.  
  796. On exit
  797.  
  798.         --
  799.  
  800. Interrupts
  801.  
  802.         Interrupt status is not defined
  803.         Fast interrupts are enabled
  804.  
  805. Processor mode
  806.  
  807.         Processor is in SVC mode
  808.  
  809. Re-entrancy
  810.  
  811.         SWI is not re-entrant
  812.  
  813. Use
  814.  
  815.         This call will lock the Dynamite heap, so that blocks will not
  816.         normally be moved around (e.g. during compaction).  Blocks may still
  817.         be moved when they are resized, however.  The heap may be unlocked
  818.         again by calling Dynamite_Unlock.  Calls to Dynamite_Lock may be
  819.         nested.
  820.  
  821.         When locked, the heap behaves much like a normal nonshifting heap,
  822.         and can become fragmented.
  823.  
  824. Related SWIs
  825.  
  826.         * Dynamite_Unlock
  827.  
  828.  
  829. Dynamite_Unlock (SWI &4A3CC)
  830.  
  831.         Unlocks the Dynamite heap
  832.  
  833. On entry
  834.  
  835.         --
  836.  
  837. On exit
  838.  
  839.         --
  840.  
  841. Interrupts
  842.  
  843.         Interrupt status is not defined
  844.         Fast interrupts are enabled
  845.  
  846. Processor mode
  847.  
  848.         Processor is in SVC mode
  849.  
  850. Re-entrancy
  851.  
  852.         SWI is not re-entrant
  853.  
  854. Use
  855.  
  856.         This call will cancel the effects of a previous Dynamite_Lock.
  857.  
  858. Related SWIs
  859.  
  860.         * Dynamite_Lock
  861.  
  862.  
  863. Dynamite_ClaimAnchor (SWI &4A3CD)
  864.  
  865.         Allocates an anchor from the RMA
  866.  
  867. On entry
  868.  
  869.         --
  870.  
  871. On exit
  872.  
  873.         R0 = address of anchor
  874.  
  875. Interrupts
  876.  
  877.         Interrupt status is not defined
  878.         Fast interrupts are enabled
  879.  
  880. Processor mode
  881.  
  882.         Processor is in SVC mode
  883.  
  884. Re-entrancy
  885.  
  886.         SWI is not re-entrant
  887.  
  888. Use
  889.  
  890.         Allocates an anchor from the RMA.  This should be used by
  891.         applications to obtain anchors, so that Dynamite does not try to
  892.         access application memory which has been paged out when it moves
  893.         blocks.
  894.  
  895. Related SWIs
  896.  
  897.         * Dynamite_ReleaseAnchor
  898.  
  899.  
  900. Dynamite_ReleaseAnchor (SWI &4A3CE)
  901.  
  902.         Releases an anchor allocated by Dynamite_ClaimAnchor
  903.  
  904. On entry
  905.  
  906.         R0 = address of anchor
  907.  
  908. On exit
  909.  
  910.         --
  911.  
  912. Interrupts
  913.  
  914.         Interrupt status is not defined
  915.         Fast interrupts are enabled
  916.  
  917. Processor mode
  918.  
  919.         Processor is in SVC mode
  920.  
  921. Re-entrancy
  922.  
  923.         SWI is not re-entrant
  924.  
  925. Use
  926.  
  927.         This SWI will allow you to release an anchor you claimed with
  928.         Dynamite_ClaimAnchor, so it can be used again.
  929.  
  930. Related SWIs
  931.  
  932.         * Dynamite_ClaimAnchor
  933.  
  934.  
  935. Dynamite_ReadSpriteSize (SWI &4A3CF)
  936.  
  937.         Reads the total size of the System Sprite Area
  938.  
  939. On entry
  940.  
  941.         --
  942.  
  943. On exit
  944.  
  945.         R0 = size of the System Sprite Area in bytes
  946.  
  947. Interrupts
  948.  
  949.         Interrupt status is undefined
  950.         Fast interrupts are enabled
  951.  
  952. Processor mode
  953.  
  954.         Processor is in SVC mode
  955.  
  956. Re-entrancy
  957.  
  958.         SWI is re-entrant
  959.  
  960. Use
  961.  
  962.         This SWI returns the size of the System Sprite Area in bytes,
  963.         including the Dynamite area if present.  It is anticipated that
  964.         programs requiring to enumerate the allocation of all memory in the
  965.         system will use code similar to the following to read the Sprite
  966.         Area size:
  967.  
  968.                 ; --- Read sprite area size ---
  969.  
  970.                 SWI     XDynamite_ReadSpriteSize
  971.                 MOVVC   R1,R0
  972.                 MOVVS   R0,#3
  973.                 SWIVS   XOS_ReadDynamicArea
  974.  
  975.  
  976. Related SWIs
  977.  
  978.         None.
  979.  
  980.  
  981. Dynamite_Describe (SWI &4A3D0)
  982.  
  983.         Describes the Dynamite area at the time of the call
  984.  
  985. On entry
  986.  
  987.         --
  988.  
  989. On exit
  990.  
  991.         R0 = handle of dynamic area, or -1 for pre-RISC OS 3.5 machines
  992.         R1 = total size of Dynamite area
  993.         R2 = size of unused area
  994.  
  995. Interrupts
  996.  
  997.         Interrupt status is undefined
  998.         Fast interrupts are enabled
  999.  
  1000. Processor mode
  1001.  
  1002.         Processor is in SVC mode
  1003.  
  1004. Re-entrancy
  1005.  
  1006.         SWI is re-entrant
  1007.  
  1008. Use
  1009.  
  1010.         This call returns some information on the Dynamite area. The sizes
  1011.         returned are only valid for the time that the caller has control and
  1012.         doesn't call another Dynamite SWI.
  1013.  
  1014. Related SWIs
  1015.  
  1016.         None.
  1017.  
  1018.  
  1019. Dynamite_IntegrityCheck (SWI &4A3D1)
  1020.  
  1021.         Performs a rigorous check of Dynamite's heap
  1022.  
  1023. On entry
  1024.  
  1025.         --
  1026.  
  1027. On exit
  1028.  
  1029.         --
  1030.  
  1031. Interrupts
  1032.  
  1033.         Interrupt status is undefined
  1034.         Fast interrupts are enabled
  1035.  
  1036. Processor mode
  1037.  
  1038.         Processor is in SVC mode
  1039.  
  1040. Re-entrancy
  1041.  
  1042.         SWI is not re-entrant
  1043.  
  1044. Use
  1045.  
  1046.         Checks the Dynamite heap carefully.  If the heap has been corrupted,
  1047.         an error is returned.  You can use this SWI during debugging of
  1048.         applications.
  1049.  
  1050.         Normally, Dynamite only performs simple checks, for performance
  1051.         reasons.  You must call this SWI by hand to check the heap fully.
  1052.  
  1053. Related SWIs
  1054.  
  1055.         None.
  1056.  
  1057.  
  1058. Dynamite_ChangeAnchor (SWI &4A3D2)
  1059.  
  1060.         Changes the address of a block's anchor
  1061.  
  1062. On entry
  1063.  
  1064.         R0 = address of the block's current anchor
  1065.         R1 = address of new anchor
  1066.  
  1067. On exit
  1068.  
  1069.         --
  1070.  
  1071. Interrupts
  1072.  
  1073.         Interrupt status is undefined
  1074.         Fast interrupts are enabled
  1075.  
  1076. Processor mode
  1077.  
  1078.         Processor is in SVC mode
  1079.  
  1080. Re-entrancy
  1081.  
  1082.         SWI is not re-entrant
  1083.  
  1084. Use
  1085.  
  1086.         Changes the address of a block's anchor.  The new anchor is set up
  1087.         correctly on exit.  The old anchor cannot be used any more, and any
  1088.         attempts to use it in Dynamite SWIs will cause an error.
  1089.  
  1090. Related SWIs
  1091.  
  1092.         None.
  1093.  
  1094. _____________________________________________________________________________
  1095.  
  1096. *Commands
  1097.  
  1098.  
  1099. *Dynamite_Clear
  1100.  
  1101.         Clears the Dynamite heap and resets Dynamite
  1102.  
  1103. Syntax
  1104.  
  1105.         *Dynamite_Clear
  1106.  
  1107. Parameters
  1108.  
  1109.         --
  1110.  
  1111. Use
  1112.  
  1113.         This command will free all the memory used by the Dynamite heap, and
  1114.         all the anchors allocated by Dynamite_ClaimAnchor.  This is useful
  1115.         during development of a program which uses Dynamite, which is not
  1116.         freeing memory correctly. Note that no confirmation is requested for
  1117.         this operation.  If applications or modules which are using Dynamite
  1118.         are running when you use this command, they will probably crash.
  1119.  
  1120.  
  1121. *Dynamite_HeapDump
  1122.  
  1123.         Displays diagnostic information about the Dynamite heap
  1124.  
  1125. Syntax
  1126.  
  1127.         *Dynamite_HeapDump
  1128.  
  1129. Parameters
  1130.  
  1131.         --
  1132.  
  1133. Use
  1134.  
  1135.         This command displays a dump of Dynamite's heap on the screen.  The
  1136.         dump contains information about the heap as a whole (its base
  1137.         address, its size, and the size of the dynamic area) followed by a
  1138.         description of every block in the heap.
  1139.  
  1140.  
  1141. *Desktop_DynamiteCompactor
  1142.  
  1143.         This command is for Dynamite internal use only.  Do not use it.
  1144.  
  1145.