home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / games / gamesuite / !Amnesia / AmsHelp / SWIDocs < prev    next >
Text File  |  1995-01-29  |  26KB  |  1,023 lines
  1.  
  2. SWI Documentation for the Amnesia module version 1.10
  3. =====================================================
  4.  
  5. Amnesia is a module which provides support for memory allocation and an
  6. 'object handler' primarily for use in video games.  The Amnesia module has
  7. many facilities and you are unlikely to need all of them.  This document
  8. contains full information regarding the SWIs so may look a bit daunting. 
  9. Don’t worry - it’s not half as complicated as it looks!
  10.  
  11. =======================================
  12.  
  13. Amnesia_Init
  14. ------------
  15.  
  16. Initialises the Amnesia module
  17.  
  18. On Entry
  19.  
  20. R0 = Area start
  21. R1 = Area length
  22. R2 = Area type
  23.  
  24. On Exit
  25.  
  26. R0 preserved
  27. R1 preserved
  28. R2 preserved
  29.  
  30. Interrupt status not altered.  Executes in SVC mode.
  31. SWI is not re-entrant. 
  32.  
  33. Use
  34.  
  35. This SWI must be issued before using any other Amnesia facilities.  R0 should
  36. be word aligned (multiple of 4).  The register meanings are as follows:
  37.  
  38. R0 = 0 : Claim from RMA.
  39.  
  40. R2 = 0 : Tidy mode - compact heap on each release of memory
  41. R2 = 1 : Messy mode - compact heap when out of space
  42. R2 = 2 : Static mode - compact heap only when instructed to do so
  43.  
  44. In tidy mode the module will shift the heap and gather all of the free space
  45. together when blocks or tables are deallocated, so the heap is always tidy
  46. and not fragmented.  In messy mode the heap will be shifted if there is not
  47. enough space for a requested allocation.  Therefore the heap is usually in a
  48. mess and fragmented.  This mode tends to give you occasional big tidy-ups
  49. instead of regular small ones.  In static mode the heap is not shifted until
  50. you specifically request it.  This is so that BASIC programs have a chance to
  51. re-read all of the pointers that they use.
  52.  
  53. To release the Amnesia block, call this SWI with R1=0.
  54.  
  55. The module can only support one heap at a time, although this heap can be
  56. split up into blocks as you please.
  57.  
  58. The SWI may return errors as the memory block is checked for validity.  All
  59. of the following SWIs will return errors if called before a successful
  60. Amnesia_Init.
  61.  
  62. =======================================
  63.  
  64. Amnesia_ClaimBlock
  65. ------------------
  66.  
  67. Claim a block of memory from the Amnesia heap.
  68.  
  69. On Entry
  70.  
  71. R0 = Address of pointer which will be used to reference the block.
  72. R1 = Length required in bytes
  73. R2 = Zero, or pointer to name string
  74. R3 = Flags
  75.  
  76. On Exit
  77.  
  78. Pointer at R0 set to point to block, or [R0] = zero if allocation failed.
  79. R1 = length allocated
  80.  
  81. Interrupts disabled in critical stages otherwise unaltered.
  82. Executes in SVC mode.  SWI must not be called from an interrupt routine.
  83.  
  84. Use
  85.  
  86. This SWI attempts to claim a block of memory within the Amnesia heap if
  87. available.  It may shift the heap in messy mode.  R1 is rounded up to be a
  88. multiple of 4.  If the call is successful the block is then yours to do what
  89. you like with.  Always use the pointer at [R0] to access the block, as it may
  90. change when the heap is tidied.  You may supply R0 = 0, but Amnesia will no
  91. longer be able to tidy the heap below the block.
  92.  
  93. The name pointed to by R2 may be up to 8 characters long and is for your use
  94. only.  Amnesia will take a copy.
  95.  
  96. The flags in R3 are as follows:
  97.  
  98. Bit 0 : If this bit is set, the block is static - it will not be moved by
  99. heap tidying.  Avoid static blocks if possible as they may cause Amnesia to
  100. waste memory.  Ideally all of your static blocks should be claimed before
  101. your moveable ones.
  102.  
  103. Bit 1 : If set, the block claimed will be quad-word aligned +4 like blocks
  104. returned by OS_Module.  The address will end in 4 (so look like &xxxxxxx4).
  105.  
  106. Bit 2 : If this bit is set, the block is assumed to be accessed by an
  107. interrupt routine (because it’s a sound sample, for example).  If so,
  108. interrupts are disabled when the block is moved during a heap tidy to prevent
  109. problems. 
  110.  
  111. Errors will be returned if there is no room.
  112.  
  113. =======================================
  114.  
  115. Amnesia_ReleaseBlock
  116. --------------------
  117.  
  118. Release a previously claimed block of memory.
  119.  
  120. On Entry
  121.  
  122. R0 = Address of pointer (as above) or zero
  123.  
  124. On Exit
  125.  
  126.  
  127. The call zeroes pointer at [R0] if release is valid ie [R0] is a pointer to
  128. an Amnesia block.
  129.  
  130. Interrupt status unchanged.
  131. Executes in SVC mode.  SWI must not be called from an interrupt routine. 
  132.  
  133. Use
  134.  
  135. This SWI will release a block which has been previously claimed with
  136. Amnesia_ClaimBlock.  If R0=0 then the whole Amnesia area is released.  In
  137. tidy mode the heap will be shifted to release the free space for future
  138. allocations.  The error Not a valid block may be returned.
  139.  
  140. =======================================
  141.  
  142. Amnesia_ExtendBlock
  143. -------------------
  144.  
  145. Extends a block which has already been claimed
  146.  
  147. On Entry
  148.  
  149. R0 = Address of current pointer to block
  150. R1 = New length required in bytes
  151.  
  152. On Exit
  153.  
  154. Pointer at [R0] may be changed if block is moved
  155. R1 = new length allocated
  156.  
  157. Interrupt status unchanged.
  158. Executes in SVC mode.  SWI must not be called from an interrupt routine. 
  159.  
  160. Use
  161.  
  162. This SWI tries to extend or shrink a previously claimed block.  The heap may
  163. be shifted in tidy or messy modes.  May return the errors No room or Not an
  164. allocated block.  Its usual method is to claim another block, copy, and then
  165. release the block to be extended.
  166.  
  167. =======================================
  168.  
  169. Amnesia_DescribeBlock
  170. ---------------------
  171.  
  172. Returns information about a block.
  173. On Entry
  174.  
  175. R0 = pointer to block or block number
  176.  
  177. On Exit
  178.  
  179. R0 = block address
  180. R1 = block size
  181. R2 = start of data area
  182. R3 = size of data area
  183. R4 = pointer to name
  184. R5 = pointer to block pointer (as passed in R0 to ClaimBlock)
  185. R6 = block flags
  186.  
  187. Interrupt status unchanged.
  188. Executes in SVC mode.  SWI is re-entrant. 
  189.  
  190. Use
  191.  
  192. This SWI returns information on a specified block.
  193.  
  194. =======================================
  195.  
  196. Amnesia_ClaimTable
  197. ------------------
  198.  
  199. Claims space for a table of objects and creates a header for that table
  200.  
  201. On Entry
  202.  
  203. R0 = Your handle for the table (0-31)
  204. R1 = Flags
  205. R2 = Zero or pointer to name
  206. R3 = Number of objects
  207. R4 = Size of a single object (bytes)
  208.  
  209. On Exit
  210.  
  211. R0-R3 Preserved
  212.  
  213. Interrupts disabled in critical stages otherwise unaltered.
  214. Executes in SVC mode.  SWI must not be called from an interrupt routine. 
  215.  
  216. Use
  217.  
  218. This SWI sets up a table for subsequent use.  A table is a list of objects
  219. which usually represent sprites on the screen (aliens, missiles etc) but can
  220. be used for other purposes.  All objects in the new table are marked as
  221. inactive.  Returns an error if the allocation fails.
  222.  
  223. R1 contains information as follows:
  224.  
  225. bit | meaning if set 
  226.  
  227. 0   - objects require collision checking facilities.
  228.  
  229. The processing of tables is detailed with the SWI Amnesia_ProcessTable.  If
  230. the collision checking bit is set a collison checking table of a default
  231. length will be claimed.
  232.  
  233. The possible errors are No room, not initialised, bad table type, bad handle.
  234.  
  235. =======================================
  236.  
  237. Amnesia_ReleaseTable
  238. --------------------
  239.  
  240. Releases a previously claimed table
  241.  
  242. On Entry
  243.  
  244. R0 = Your handle for the table (0-31)
  245.  
  246. On Exit
  247.  
  248. R0 preserved
  249.  
  250. Interrupts disabled in critical stages otherwise unaltered.
  251. Executes in SVC mode.  SWI must not be called from an interrupt routine. 
  252.  
  253. Use
  254.  
  255. Releases the space used by a table and its collision checking area if
  256. present.  May return errors if the table is corrupted.
  257.  
  258. =======================================
  259.  
  260. Amnesia_ExtendTable
  261. -------------------
  262.  
  263. *** This SWI is not implemented ***
  264. *** Please contact the author if you _really_ need it! ***
  265.  
  266. On Entry
  267.  
  268. R0 = Your handle for the table (0-31)
  269.  
  270. R2 = New number of objects
  271.  
  272. On Exit
  273.  
  274. R0, R2 Preserved
  275.  
  276. Interrupts disabled in critical stages otherwise unaltered.
  277. Executes in SVC mode.  SWI must not be called from an interrupt routine. 
  278.  
  279. Use
  280.  
  281. This SWI extends or shrinks a current table if possible.  Shrinking it may
  282. delete objects.  All new objects in the table are marked as inactive.  Errors
  283. are generated if the extend fails.
  284.  
  285. =======================================
  286.  
  287. Amnesia_WipeTable
  288. -------------------
  289.  
  290. On Entry
  291.  
  292. R0 = Your handle for the table (0-31)
  293.  
  294. On Exit
  295.  
  296. R0 corrupted, others preserved.
  297.  
  298. Interrupts disabled in critical stages otherwise unaltered.
  299. Executes in SVC mode.  SWI must not be called from an interrupt routine. 
  300.  
  301. Use
  302.  
  303. This SWI marks all objects in the specified table as inactive.
  304.  
  305. ======