home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / LK_V1.06.LHA / LK V1.06 / HELP / auto.hlp < prev    next >
Encoding:
INI File  |  1994-11-01  |  7.5 KB  |  256 lines
  1. [LANGUAGE english; PARENT index; PAGE 4]
  2. [C;6;B]        Auto-Initialisation
  3.         Auto-Exit
  4. [J;1;N]
  5.   lk actually supports two types of intialisation and \
  6. exit code. Those are from:
  7. [C;3; GOTO slink]        Slink
  8. [1]            and
  9. [3; GOTO dice]            DICE
  10. [J]
  11. [LABEL slink; 5]  . Slink's autos:
  12. [1]
  13.   This mode needs the use of the option SLINK.
  14.  
  15.   To have auto-initialisation, SAS/C creates functions \
  16. named __STI<function name> or @_STI<function name> (The \
  17. second one correspond to the same function called with \
  18. registers not saved on the stack.) Those are called \
  19. 'CREATORS.'
  20.   To have auto-exit, SAS/C creates functions named \
  21. __STD<function name> or @_STD<function name>. Those \
  22. are called 'DESTRUCTORS.'
  23.   The code (or data) which needs those initialisation and \
  24. exit functions is created into the same unit.
  25.   The disaventage of this method is to create a relocation \
  26. pointer for each function. This has a high time and space \
  27. cost. The following initialisation method does not have \
  28. that disaventage.
  29. [5]
  30.   The following example is an illustration of the \
  31. functions of SAS/C. Note that's not a copy of it. \
  32. Nothing oblige you to use those models.
  33. [1]
  34.   To call each of those functions, you need a function \
  35. called '___construct'. lk will create two lists one \
  36. after another both terminated with a null pointer and \
  37. before the first one a pointer to the '___construct' \
  38. function will be saved. In C, the declarations are:
  39. [2]
  40.     int (*)(void) __ctors[[];
  41.     void (*)(void) __dtors[[];
  42.  
  43.   /* construct is called with ctors and dtors */
  44.     extern int __construct(int (*)(void)[[]);
  45.  
  46.   with '__ctors[[-1] == __construct'
  47.   and  '__ctors[[LASTFUNC + 1] == 0'
  48. [1]
  49.   Example of the functions which will call '___construct':
  50. [2]
  51.   int __init()
  52.   {
  53.     return (__construct(_ctors));
  54.   }
  55.  
  56.   int __exit()
  57.   {
  58.     return (__construct(_dtors));
  59.   }
  60. [1]
  61.   Of course you will have to call those two functions.
  62.  
  63.   Example of '___construct' function:
  64. [2]
  65.   int __construct(int (_tors*)(void))
  66.   {
  67.     int r = 0;
  68.  
  69.     while(*_tors) {
  70.  /* This suppose destructors always returns 0 */
  71.       if(!r) r = (*_tors)();
  72.       _tors++;
  73.     }
  74.  
  75.     return (r);
  76.   }
  77. [1]
  78.   Note: SAS/C has a flag to know if the called functions \
  79. are the creators or the destuctors.
  80.  
  81.   The object file looks like:
  82. [2]
  83.     hunk_unit  <unit name>
  84.     hunk_name  <hunk name>
  85.     hunk_code  <680x0 code>
  86.                (it could be a hunk of data)
  87.     hunk_ext   <ext_def: user function(s)>
  88.                and other externals
  89.     hunk_end
  90.     hunk_name  <init hunk name>
  91.     hunk_code  <680x0 code>
  92.     hunk_ext   <ext_def: __STI<user function>
  93.                and other externals
  94.     hunk_end
  95.     hunk_name  <exit hunk name>
  96.     hunk_code  <680x0 code>
  97.     hunk_ext   <ext_def: __STD<user function>
  98.                and other externals
  99.     hunk_end
  100. [1]
  101.   Note: there is no need to have STI/STD functions into \
  102. another hunk of code, each function or hunk name can be \
  103. different, some data or bss hunks can exist and any hunk \
  104. can have the usual debug and symbols.
  105.  
  106.   To ensure that the order is respected, the creators and \
  107. destructors names can include a level. The creator function \
  108. with the lower level will be called first and the higher \
  109. level will be called last. For the destructor functions the \
  110. order is inverted; functions with the lower level will be \
  111. called last and functions with the higher level will be \
  112. called first. When no level is included the default is \
  113. used, also 30000. The level is a long word value. \
  114. Functions with the same level are called in the \
  115. order they were defined (Now lk does not garantie \
  116. it.)
  117.   There is the generic syntax:
  118.      __ST?[[_]<value><user function name>
  119.   any number of underscore (_) may appear before the value.
  120.  
  121.   Example of names:
  122. [2]    __STI3890_MyInit     (Called before defaults)
  123.     @_STD__81956_MyExit  (Called after defaults)
  124. [1]
  125.   The initialisation function, in C, is declared as:
  126. [2]     extern int _STImyinit(void);
  127. [1]  when a creator returns TRUE (a value other than null) \
  128. following creators will not be called.
  129.  
  130.   The exit function, in C, is declared as:
  131. [2]     extern void _STDmyexit(void);
  132. [1]  with the default SAS/C '___construct' function all \
  133. descriptors are always called, even the corresponding \
  134. initialisation has never took place.
  135.  
  136.   How to use it:
  137.  
  138.     For instance, if you define a function which needs \
  139. the IntuitionBase, you will write:
  140. [2]
  141.   external void *Intuition;
  142.   ...
  143.     #asm
  144.       MOVEA.L _Intuition(A6)
  145.       JSR _LVOOpenWorkBench(A6)
  146.     #endasm
  147.   ...
  148. [1]
  149.     Then the corresponding initialisation and exit will be:
  150. [2]
  151.   void *Intuition;
  152.   _STI_OpenIntuition()
  153.   {
  154.     Intuition = OldOpenLibrary
  155. [R]            ("intuition.library");
  156. [L]    return (!Intuition);
  157.   }
  158.  
  159.   void *Intuition;
  160.   _STD_CloseIntuition()
  161.   {
  162.     if(Intuition) {
  163.       CloseLibrary(Intuition);
  164.       Intuition = (void *) 0;
  165.     }
  166.   }
  167. [1]
  168. [LABEL dice; 5]  . DICE's autos:
  169. [1]
  170.   This mode needs the use of the option BLOCKUNIT \
  171. (and eventually CC.) The use of DICE is needed only \
  172. if you use DICE object files.
  173.  
  174.   dlink, to have auto-initialisation, uses the hunk names \
  175. autoinit and autoexit. Those names might be modified as \
  176. you want with lk, there is no restriction.
  177.   Because all hunks with the same name are linked together, \
  178. all autoinit and autoexit will be. Those hunks will be found \
  179. in the same unit than the function/data which needs to be \
  180. initialized. You need to have one hunk for the user function \
  181. or data, one hunk for the initialisation and one hunk for the \
  182. exit code. To produce several levels, several names are \
  183. used (like autoinit0, autoinit1, ...) The header will call \
  184. each of those groups of hunks one after another.
  185.  
  186.   Actually DICE uses autoinit0, autoinit1, autoexit0, \
  187. autoexit1 and autoconfig. The only problem in DICE is \
  188. the file 'c.o' which have some relocation pointing to \
  189. empty hunks. This could be avoided by creating hunks \
  190. with NOP's instructions. Anyway lk handled them, but \
  191. it needs the use of the option DICE.
  192.   The difference for DICE between the autoinits and \
  193. autoconfig is that autoinits may fail.
  194.  
  195.   The functions of initialisation or of exit does not \
  196. have the usual RTS at the end. This also enable, with \
  197. a single call, to execute all functions of a given level. \
  198. To create that kind of hunks you may use DICE which \
  199. enables initialisation and exit functions or use \
  200. your prefered assembler. You will have to verify that \
  201. your assembler finish your hunks of code with a NOP \
  202. when your code is not long word aligned.
  203.  
  204.   The last object file will also contains all \
  205. init/exit hunks with that simple hunk of code \
  206. which is the RTS. In DICE that file is the 'x.o' \
  207. object. An RTS instruction will be used while initializing \
  208. if you need to report a failure. DICE have a function \
  209. named '__AutoFail' for this purpose.
  210.  
  211.   Note: all hunks having one of those names must be \
  212. of type code.
  213.  
  214.   Example:
  215.  
  216.   file 'c.a'
  217. [2]
  218.     ...
  219.     JSR     _autoinit0
  220.     BEQ     .error      ;Exit now
  221.     JSR     _autoinit1
  222.     BEQ     .error
  223.     JSR     __main
  224.     JSR     _autoexit0  ;The order is user choice
  225.     JSR     _autoexit1
  226.     ...
  227. [1]
  228.   file 'myinit.a'
  229. [2]
  230.     LEA      _cnttable,A0
  231.     MOVE.W  #$00FF,D0
  232. .next
  233.     MOVEQ   #$00,D1
  234.     MOVEQ   #$07,D2
  235. .cnt
  236.     BTST.B  D2,D0
  237.     BEQ.B   .iszero
  238.     ADDQ.B  #$01,D1
  239. .iszero
  240.     DBF     D2,.cnt
  241.     MOVE.B  D1,(A0)+
  242.     DBF     D0,.next
  243.                         ;<- NO RTS!
  244. [1]
  245.   file 'x.a'
  246. [2]
  247.     RTS
  248. [1]
  249.   See also:
  250. [L;3][LINK block]            BLOCKUNIT
  251. [LINK block]                BLOCKHUNK
  252. [LINK cc]                CC
  253. [LINK dice]                DICE
  254. [LINK slink]                SLINK
  255. [5; LINK about; GOTO address]        Become Registred
  256.