home *** CD-ROM | disk | FTP | other *** search
/ Reverse Code Engineering RCE CD +sandman 2000 / ReverseCodeEngineeringRceCdsandman2000.iso / RCE / LordLucifer / win32asm / files / win32asm.exe / Win32ASM / ASMInc / InitExit.mac < prev    next >
Encoding:
Text File  |  1997-09-02  |  10.1 KB  |  217 lines
  1. ; Macros to handle initialization and exit routines. Ph.A., 03 Jan 97.
  2.  
  3. ; $Id: InitExit.mac 1.1 1997/09/02 09:50:35 Philippe Exp $
  4.  
  5. ; $Log: /Win32Equ/InitExit.mac $
  6. ; 
  7. ; 1     18/09/97 14:24 Philippe
  8. ; Initial checkin into SourceSafe.
  9. ; Revision 1.1  1997/09/02 09:50:35  Philippe
  10. ; Initial revision
  11. ;
  12.  
  13.  
  14.  
  15. ; These macros allow the definition of initialization routines in multiple
  16. ; library modules. The $InitRoutine is used in any module containing an
  17. ; initialization routine that must be executed before the main logic of
  18. ; a program can be started.
  19. ; A typical use for an initialization routine is to create resources, such
  20. ; as critical sections, semaphores, etc... that will be required later by
  21. ; routines called in a multithreaded context.
  22. ; The resources must obviously be created and initializated before the
  23. ; threads that use them are created, and must be released before the
  24. ; program exits. One can of course invoke the initialization routines
  25. ; explicitely in the startup code of the application, but this is tedious
  26. ; and error prone: one could call a library routine and forget to add
  27. ; the code to init/exit the the package. Or one could stop using the
  28. ; library routine and forget to remove the call to the init and/or exit
  29. ; routines, resulting in the library module still being (needlessly)
  30. ; linked in.
  31. ; The $InitRoutine, $ExitRoutine, $RunInitRoutines and $RunExitRoutines
  32. ; are designed to help handling this problem.
  33. ; $InitRoutine and $ExitRoutine are used to declare initialization and
  34. ; exit routines.
  35. ; $InitRoutine declares a segment, naming it @Init$<module name>.
  36. ; $ExitRoutine declares a segment, naming it @Exit$<module name>.
  37. ; So if invoked in .ASM module FOO, $InitRoutine and $ExitRoutine will
  38. ; create segments named @Init$FOO and @Exit$FOO respectively.
  39. ; Both macros are called with the name of a routine. The macro will
  40. ; generate a DWORD pointer to the routine, and place this pointer in the
  41. ; @Init$ (or @Exit$) segment/section.
  42. ; The following is en excerpt from the PE object definition in the
  43. ; document "Microsoft Portable Executable and Common Object File Format
  44. ; Specification 4.1". When a section (segment) name contains a '$' sign,
  45. ; a PE linker processes it specially:
  46. ; "The "$" character (dollar sign) has a special interpretation in section
  47. ; names in object files. When determining the image section that will
  48. ; contain the contents of an object section, the linker discards the "$"
  49. ; and all characters following it. Thus, an object section named .text$X
  50. ; will actually contribute to the .text section in the image. However, the
  51. ; characters following the "$" determine the ordering of the contributions
  52. ; to the image section. All contributions with the same object-section
  53. ; name will be allocated contiguously in the image, and the blocks of
  54. ; contributions will be sorted in lexical order by object-section name.
  55. ; Therefore, everything in object files with section name .text$X will end
  56. ; up together, after the .text$W contributions and before the .text$Y
  57. ; contributions.
  58. ; The section name in an image file will never contain a "$" character."
  59.  
  60. ; As a result, the contents of all "@Init$" segments will be concatenated
  61. ; in the "Init" section and the contents of all "@Exit$" sections will be
  62. ; concatenated in the "@Exit" section.
  63. ; So the @$InitRoutine macros of all modules contribute to the construction
  64. ; of a global table containing all the addresses of the initialization
  65. ; routines and located in section "@Init", and the $ExitRoutine contribute
  66. ; to the construction of a global table containing all the addresses of
  67. ; the Exit routines and located in section "@Exit".
  68. ; The $RunInitRoutines and $RunExitRoutines put all of this together:
  69. ; they create the "@Init$" and "@Exit$" segments (that will endup ahead of
  70. ; all other @Init and @Exit segments in collating sequence and contain the
  71. ; table label), and "@Init$zzzzzzzz" / "@Exit$zzzzzzzz" (that will hopefully
  72. ; endup after all other @Init and @Exit segments and contain a DWORD 0 as
  73. ; an end of table marker).
  74. ; Finally, each macro generates a short loop that goes down its associated
  75. ; list and calls the addresses in the list.
  76. ; So at the point in code where the $RunInitRoutines macro will be
  77. ; inserted, there will be a loop that will call all init routines
  78. ; belonging to the modules that have been linked in.
  79. ; Ditto for $RunExitRoutines.
  80. ; The Init/Exit routines will automatically be invoked at the right time
  81. ; if the library module that contains them is pulled in by the linker,
  82. ; and only then. In case the Init and/or Exit routines must be ordered
  83. ; somehow, it is possible to pass a second parameter to the $????Routine
  84. ; declaration. This second parm is concatenated in the segment name
  85. ; ahead after the @Init$ (@Exit$) and before the <module name>.
  86. ; It allows one to change the linking order and force the Init (Exit)
  87. ; routines to execute in any requested order. For instance, a "Console Log"
  88. ; routine might need initialization before any other routine so the
  89. ; other initialization routines might use the Console Log procs to
  90. ; log what they did. Passing a second parameter of "0" might force the
  91. ; console log init routine to move up the list (if no other module uses
  92. ; this and no module is named "0.ASM").
  93.  
  94.  
  95. ; Call all initialization routines declared through the $InitRoutine macro.
  96. ; This macro should be inserted in the .CODE section.
  97.  
  98. ; If one of the initialization routine fails badly enough to prevent the
  99. ; program to run, it should return with the Carry flag set.
  100. ; This will abort the init loop.
  101. ; The code invoking the $RunInitRoutine should test the Carry condition
  102. ; and directly jump to some abort / exit code if it is set.
  103.  
  104. ; The FirstRoutine label shouldn't need to be made public, specially since
  105. ; it's a local macro symbol.
  106. ; Unfortunately, MASM/LINK generate a 0000000000 offset in the subsequent
  107. ; MOV ESI,OFFSET instruction if we don't make it public!
  108. ; Owell.
  109.  
  110. $RunInitRoutines MACRO
  111.     LOCAL FirstRoutine
  112.                 ;DO NOT REMOVE THIS NOP!
  113.                 ;This macro will reveal a MASM bug where MASM will generate
  114.                 ;a scrogged prologue code sequence, when $RunINitRoutines
  115.                 ;used as the first code generating instruction
  116.                 ;in a PROC *and* the PROC has a local variable.
  117.     NOP         ;Adding this NOP cures the bug...
  118.  
  119.                 ;Declare the first section in the @Init group.
  120. @Init$          SEGMENT DWORD READONLY PUBLIC USE32 'DATA'
  121. FirstRoutine    LABEL NEAR
  122.                 PUBLIC FirstRoutine     ;Head of Init pointer table.
  123. @Init$          ENDS
  124.                 ;Declare the last section in the @Init group.
  125. @Init$zzzzzzzz  SEGMENT DWORD READONLY PUBLIC USE32 'DATA'
  126.                 DWORD 0                 ;Define the terminator of the
  127. @Init$zzzzzzzz  ENDS                    ;@Init table.
  128.  
  129.     .CODE
  130.  
  131.     MOV ESI,OFFSET FirstRoutine         ;Point to first entry in Init
  132.                                         ;routines table.
  133.       .REPEAT
  134.       MOV EAX,[ESI]                     ;Get first Init address,
  135.       .BREAK .IF EAX == 0               ;exit at end of table.
  136.       SAVE ESI                          ;Save table pointer,
  137.       CALL EAX                          ;call current Init routine,
  138.       RESTORE ESI                       ;restore init table pointer,
  139.       .BREAK .IF CARRY?                  ;Exit init loop if init routine failed.
  140.       LEA ESI,[ESI]+(SIZEOF DWORD)      ;Bump to next init routine pointer,
  141.       .FOREVER                          ;loop again.
  142.  
  143.     ENDM
  144.  
  145.  
  146. ; Call all exit routines declared through the $ExitRoutine macro.
  147. ; This macro should be inserted in the .CODE section.
  148. ; We ignore any error condition in the termination routines, as we
  149. ; are terminating anyway.
  150.  
  151. $RunExitRoutines MACRO
  152.  
  153.                 ;Declare the first section in the @Exit group.
  154. @Exit$          SEGMENT DWORD READONLY PUBLIC USE32 'DATA'
  155. FirstRoutine    LABEL NEAR
  156.                 PUBLIC FirstRoutine     ;Head of Exit pointer table.
  157. @Exit$          ENDS
  158.                 ;Declare the last section in the @Exit group.
  159. @Exit$zzzzzzzz  SEGMENT DWORD READONLY PUBLIC USE32 'DATA'
  160.                 DWORD 0                 ;Define the terminator of the
  161. @Exit$zzzzzzzz  ENDS                    ;@Exit table.
  162.  
  163.  
  164.     .CODE
  165.  
  166.     MOV ESI,OFFSET FirstRoutine         ;Point to first entry in Init
  167.                                         ;routines table.
  168.       .REPEAT
  169.       MOV EAX,[ESI]                     ;Get first Init address,
  170.       .BREAK .IF EAX == 0               ;exit at end of table.
  171.       SAVE ESI                          ;Save table pointer,
  172.       CALL EAX                          ;call current Init routine,
  173.       RESTORE ESI                       ;restore init table pointer,
  174.       LEA ESI,[ESI]+(SIZEOF DWORD)      ;Bump to next init routine pointer,
  175.       .FOREVER                          ;loop again.
  176.  
  177.     ENDM
  178.  
  179.  
  180. ; Declare a routine as an Init routine.
  181. ; Its address is placed in the special @Init segment.
  182. ; The Prefix parm can be used to force order of init routines: the prefix
  183. ; parm is inserted after the Init$ root and before the module name.
  184. ; An Init routine that fails should give any relevant diagnostic and
  185. ; return with the Carry flag set. This will abort the execution of Init
  186. ; routines (NOT any following Init routine will be executed).
  187.  
  188. $InitRoutine MACRO Address:REQ,Prefix
  189.     LOCAL Address,SegInitName,Prefix
  190.  
  191. ;SegInitName TEXTEQU @CatStr(@Init$,%Prefix,%@FileName)
  192. SegInitName TEXTEQU @CatStr(@Init$,&Prefix,%@FileName)
  193.  
  194. %SegInitName SEGMENT DWORD READONLY PUBLIC USE32 'DATA'
  195.     DWORD Address
  196. %SegInitName ENDS
  197.     ENDM
  198.  
  199.  
  200. ; Declare a routine as an Exit routine.
  201. ; Its address is placed in the special @Exit segment.
  202. ; The Prefix parm can be used to force order of init routines: the prefix
  203. ; parm is inserted after the Init$ root and before the module name.
  204.  
  205. $ExitRoutine MACRO Address:REQ,Prefix
  206.     LOCAL Address,SegExitName,Prefix
  207.  
  208. ;SegExitName TEXTEQU @CatStr(@Exit$,%Prefix,%@FileName)
  209. SegExitName TEXTEQU @CatStr(@Exit$,&Prefix,%@FileName)
  210.  
  211. %SegExitName SEGMENT DWORD READONLY PUBLIC USE32 'DATA'
  212.     DWORD Address
  213. %SegExitName ENDS
  214.     ENDM
  215.  
  216.  
  217.