home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / LK_V1.06.LHA / LK V1.06 / HELP / ovl.hlp < prev    next >
Encoding:
INI File  |  1994-11-01  |  7.8 KB  |  199 lines
  1. [LANGUAGE english; PARENT index; PAGE 15]
  2. [C;6;B]        The overlays
  3. [J;1;N]
  4.   Only the commercial version will have this instruction fully \
  5. supported. Registred people will receive that version.
  6.  
  7.   The purpose of overlays is to have really big programs not \
  8. entirely in memory at a time. The overlay manager will take \
  9. care of memory allocations and dispositions.
  10.   To make the main code the smaller than posible, all library \
  11. hunks which are used only by a specific overlaid unit will \
  12. be linked into that unit. This will save execution time and \
  13. space.
  14.  
  15.   To correctly show you the difference between an overlay \
  16. hunk and an overlay unit there is a diagram:
  17.  
  18.   let's say that we have a WITH file which contains:
  19.  
  20. [B]        OVERLAY
  21. [B]          palette.o
  22.           stencil.o
  23.           brushmodes.o
  24. [B]        END
  25. [B]
  26.   knowing that each object file contains a hunk of code \
  27. and a hunk of DATA or BSS, the following diagram show \
  28. you how each file is saved inside the final overlaid \
  29. executable:
  30.  
  31.   +-----------------+   Unit 1 (palette.c)
  32.   |                 |
  33.   | +-------------+ |     Hunk n
  34.   | |  HUNK_CODE  | |
  35.   | +-------------+ |
  36.   |                 |
  37.   | +-------------+ |     Hunk n+1
  38.   | |  HUNK_DATA  | |
  39.   | +-------------+ |
  40.   |                 |
  41.   +-----------------+
  42.  
  43.   +-----------------+   Unit 2 (stencil.c)
  44.   |                 |
  45.   | +-------------+ |     Hunk n+2
  46.   | |  HUNK_CODE  | |
  47.   | +-------------+ |
  48.   |                 |
  49.   | +-------------+ |     Hunk n+3
  50.   | |  HUNK_BSS   | |
  51.   | +-------------+ |
  52.   |                 |
  53.   +-----------------+
  54.  
  55.   +-----------------+   Unit 3 (brushmodes.c)
  56.   |                 |
  57.   | +-------------+ |     Hunk n+4
  58.   | |  HUNK_CODE  | |
  59.   | +-------------+ |
  60.   |                 |
  61.   +-----------------+
  62. [INDENT 6]
  63.   (*) where n is the number of hunk is the root part.
  64. [INDENT]
  65.   Of course, each hunk of CODE, DATA and BSS may have some \
  66. attached hunks of DEBUG, SYMBOL and RELOCation. If you \
  67. need to refer a hunk in overlay, you just need its unit \
  68. number.
  69.  
  70.   The overlay section of lk does not follow the way it was \
  71. designed by Commodore. No tree has to be respected, every unit \
  72. can call every other unit, lk will take care of that. Calls to an \
  73. external module can be done with a JSR/JMP and BSR/BRA \
  74. instructions as well. lk will automatically generates the overlay \
  75. tables needed to permit those calls (If you used BSR/BRA \
  76. assembly instructions, you will probably need the use of the ALV \
  77. command.)
  78.   Note that calls from an overlaid hunk to any of the root hunks \
  79. is just part of the relocation informations. Only calls from the \
  80. root to the overlaid units or calls from overlaid units to other \
  81. overlaid units generate overlay tables.
  82.   An overlay call is very long and you MUST avoid them in loops. \
  83. It actually includes around 20 assembly instructions. To ensure \
  84. faster calls, you should use the SMALLCODE command. This will \
  85. avoid the research of the CODE hunk to call.
  86.   An overlay unit may consist of DATA only. In that case, \
  87. an access will be granted only after a call to the overlay \
  88. handler loader.
  89.   After a call returns from an external function, the called \
  90. funtion is no longer residing in memory. No direct access can \
  91. be realised (Even if that function is keept in memory by the \
  92. default overlay handler.) This means no pointer on static \
  93. data can be returned from an overlaid hunk. Note that \
  94. the special NODATAOVERLAID command can be used to enable this \
  95. kind of programming. Have a look to the instruction \
  96. NODATAOVERLAID to see some examples.
  97.   You may force all overlaid hunks to be loaded at a time \
  98. with a call to the 'ovl_load' function.
  99.  
  100.   If you are linking C objects which access their data in an \
  101. unknown way, you may take the risk to have problems with \
  102. those data because they are no more available after the \
  103. last return from an overlaid function. To prevent that \
  104. problem the NODATAOVERLAID instruction will move all \
  105. DATA and BSS hunks into the main program.
  106.   Note: this is required if you use a small memory model (?!?) \
  107. But lk will automatically handle the data displacement and \
  108. NODATAOVERLAID use not necessary.
  109.  
  110.   When loaded with the default overlay handler, hunks \
  111. are NOT linked like they are with LoadSeg() of AmigaDOS. The \
  112. segments have height bytes at the beginning with the size \
  113. and the 68000 pointer to the next segment.
  114.   Each unit is a new linked list (Units are never linked \
  115. together.)
  116.  
  117.   The available functions from the default overlay handler are \
  118. listed and explained below. Those are available into the \
  119. 'overlay.h' header.
  120. [5]
  121.     hunk_pointer _ovl_load(unit_number)
  122.  
  123.     void *ovl_load(long);
  124. [INDENT 4; 1]
  125.       The parameter is the number of the unit to be loaded. \
  126. This call will increase the access counter by one. This \
  127. function might be called to ensure the physical presence \
  128. of a unit in memory, especially if that unit is only \
  129. composed of data.
  130.       The returned pointer is the startup to the first hunk of \
  131. that overlay unit. This is a normal 68000 pointer, not a BCPL.
  132.       If you call this function with -1, all units will be loaded \
  133. in memory and then available at any time. In this case this \
  134. function returns DOSTRUE when no error occured, otherwise \
  135. DOSFALSE. To know a unit pointer you will have to call \
  136. 'ovl_load' again with a specific unit number. A call to \
  137. 'ovl_release' enable the system to suppress the lock.
  138. [INDENT; 5]
  139.     success _ovl_release(unit_number)
  140.  
  141.     long ovl_release(long);
  142. [INDENT 4; 1]
  143.       Release the specified unit from its lock. This function reduce \
  144. the access counter by one, but does not free the corresponding units \
  145. memory, even the counter drop to zero. The free is realised with the \
  146. 'ovl_dispatch' function.
  147.       If you need a data hunk temporary in memory, you may call the \
  148. 'ovl_load' function and then the 'ovl_release' and 'ovl_dispatch' \
  149. to free it when you do not need it any longer.
  150. [INDENT; 5]
  151.     success _ovl_dispatch(unit_number)
  152.  
  153.     long ovl_dispatch(long);
  154. [INDENT 4; 1]
  155.       Try to free the specified unit from memory. It only works \
  156. when the access counter is null. You might pass -1 as parameter \
  157. to discard all units which can actually be freed.
  158. [INDENT; 5]
  159.     success _ovl_freehook(free_func)
  160.  
  161.     long ovl_freehook(void (*)(long));
  162. [INDENT 4; 1]
  163.       When the overlay handler needs to load a new hunk, it may \
  164. fails with the memory allocation. Then it will free all memory \
  165. buffers reserved for other unused units. If the allocation \
  166. fails again a call to a user function is processed.
  167.       If that function is able to free some memory, it will return \
  168. and the overlay handler will try again to load the needed unit. \
  169. If it does not work a second call will be processed to the \
  170. user function... and so on. Each new call to the user function \
  171. will be done with an incremented parameter starting from null. \
  172. On zero the user should free unused data, on one it should free \
  173. every thing it can and on 2 it should quit on an 'out of memory' \
  174. error (except if the unit is not necessary...)
  175.       The overlay handler will call that function with -1 if it \
  176. has a problem loading the unit (AmigaDOS error.)
  177.       If no user function is defined and the new hunk can not be \
  178. loaded, the function 'ovl_call' will return with all registers \
  179. unchanged (including CCR) giving the impression of an empty call.
  180.  
  181.       Note: the parameter is given in D0 and on the stack.
  182. [INDENT]
  183.  
  184.   The overlay handler program is given with this product \
  185. to enable programmers to make mofications and eventually \
  186. transform it completly. See also the instruction OVERLAYOBJECT \
  187. for more informations.
  188. [INDENT]
  189.   See also:
  190. [L;3][LINK alv]                ALV
  191. [LINK autooverlay]            AUTOOVERLAY
  192. [LINK filename]                <filename>
  193. [LINK nodataoverlaid]            NODATAOVERLAID
  194. [LINK nospecialdebug]            NOOVLDEBUG
  195. [LINK overlay]                OVERLAY
  196. [LINK overlayobject]            OVERLAYOBJECT
  197. [LINK shortreloc]            SHORTRELOCOVERLAY
  198. [5; LINK about; GOTO address]        Become Registred
  199.