home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / new / util / libs / sslib / ssmac.doc < prev    next >
Text File  |  1994-12-12  |  7KB  |  189 lines
  1.  
  2.                              Special Support Macros
  3.  
  4.                                   Version 3.4
  5.  
  6.             (c) 1993,1994 MJSoft System Software, SinSoft and PCSoft
  7.  
  8. ================================================================================
  9.  
  10. ### Typical structure of program which uses the macros: ###
  11.  
  12. ;DEBUG    set    1        ; Set only when debugging and your
  13.                 ; debugger doesn't pass the arguments
  14.                 ; correctly (see StartupInit doc)
  15.  
  16.     include    "ssmac.h"    ; include the macros
  17.     [tbase    a4]        ; define text base register if you want
  18.     start            ; or clistart if you want only CLI
  19. ; here is automatically defined the "go" label
  20.  
  21.     ; here is your program
  22.  
  23.     tags            ; start of tag list
  24.     ; here are your tags
  25.     finish            ; end of tag list
  26.     end
  27.  
  28.  
  29. ### Universal macros ###
  30.  
  31. push    r/m        - store register/memory onto stack
  32. pop    r/m        - get register/memory from stack
  33. mpush    reglist        - store register list onto stack
  34. mpop    reglist        - get register list from stack
  35. rptr    label        - store relative pointer to specified label
  36.  
  37. ### Variable definition macros ###
  38.  
  39. dv.size    name        - define variable, size={b,w,l}
  40. dbuf[.size]    name,nritems    - define buffer of nritems items size={b,w,l},
  41.               default=byte
  42. alignlong            - longword-align the variables
  43. get.type    from,to        - MOVE.type <variable>,<to>
  44. put.type    from,to        - MOVE.type <from>,<variable>
  45. geta    from,to        - LEA <variable>,<to>
  46. getad    from,via,to    - LEA <var>,<via> ; MOVE.L <via>,<to>
  47. clv.type    dest        - CLR.type <variable>
  48. tsv.type    src        - TST.type <variable>
  49.  
  50. ### Variable manipulation macros ###
  51.  
  52. vpush    var        - push longword variable onto stack
  53. vpop    var        - pop longword variable from stack
  54.  
  55.   - following macros are clones of standard instructions manipulating with
  56.     variables. 'v' on the left means that source is a variable, 'v' on the right
  57.     means that destination is a variable:
  58.  
  59. negv.size    to
  60. notv.size    to
  61. stv.size    to
  62. clrv.size    to
  63. seqv.size    to
  64. snev.size    to
  65. sccv.size    to
  66. scsv.size    to
  67. tstv.size    from
  68. bchgv    bitnr,byte
  69. bclrv    bitnr,byte
  70. bsetv    bitnr,byte
  71. btstv    bitnr,byte
  72. subqv.type    nr,byte
  73. addqv.type    nr,byte
  74. vpea    var
  75. eorv.type    src,dest
  76. divsv    src,dest
  77. divuv    src,dest
  78. mulsv    src,dest
  79. muluv    src,dest
  80. addv.type    src,dest
  81. vadd.type    src,dest
  82. andv.type    src,dest
  83. vand.type    src,dest
  84. cmpv.type    src,dest
  85. vcmp.type    src,dest
  86. movev.type    src,dest
  87. vmove.type    src,dest
  88. orv.type    src,dest
  89. vor.type    src,dest
  90. subv.type    src,dest
  91. vsub.type    src,dest
  92. vlea    src,dest
  93. vmovev.type    src,dest
  94. movemv.type    src,dest
  95. vmovem.type    src,dest
  96.  
  97. ### Text macros ###
  98.  
  99. tbase    basereg        - define text base register, must be before START
  100. dt.[c][l]    [label,]text    - define a text in text section
  101.                 l = put NL character after the text
  102.                 c = don't put 0 character after the text
  103. gett    textlabel,areg    - get address of text to <areg>
  104. tlea    textlabel,areg    - same as above
  105. dtl    text,areg    - define text and load its address
  106. tpea    text        - push address of text
  107.  
  108. ### System interface ###
  109.  
  110. call    [base,]name    - call function <name> of specified library
  111.               if no library is specified, it will use current
  112.               contents of A6 as the base
  113. jump    [base,]name    - jump to function <name> ... see CALL
  114.  
  115. ### Startup and exit ###
  116.  
  117. start            - perform standard startup and open ss.library
  118. clistart            - START with no respect to WorkBench
  119. tags            - start final declaration of tags
  120. finish            - end of tag list, inserts size of variables
  121.  
  122. ### Startup tags ###
  123.  
  124. wbconsole            - open console window when started from WorkBench
  125. template    <template>    - set template, followed by dv.l <name> for each
  126.               argument
  127. exitrout    routine        - <routine> will be called before exit
  128. errrout    routine        - <routine> will be called for error messages
  129.               (see SSLib.doc/ReportError)
  130. library    name,version    - open library and define variable containing
  131.               its base; error if not available;
  132. trylib    name,version    - same as LIBRARY, but doesn't fail if not available
  133. cputype    min,max        - require CPU 680<min>0 to 680<max>0, max=-1 for
  134.               no limit
  135. fputype    min,max        - require FPU in specified range, see SS.i
  136. sysver    min,max        - require kickstart version min..max, max=-1...
  137. diserr    flags        - disable error messages specified by flags
  138.               (it's a bit field with the same format as
  139.               sv_errors)
  140. wbconname    name        - open console window with specified name when
  141.               started from WorkBench
  142. usrtrk    tablelabel    - define user tracker types (see UserTrkTypes)
  143. extrahelp    [<string>]    - define extra help string. If no argument is
  144.               given, you should continue with sequence of
  145.               DC.Bs ended by ENDHELP
  146. endhelp            - end of extra help string (see EXTRAHELP)
  147.  
  148. ### Text output macros ###
  149.  
  150. write    <text>        - write text to standard output
  151. writeln    <text>        - write text followed by NL to standard output
  152. printfs[.L]    <text>        - write formatted text to std. output
  153.               parameters are stored on the stack, .L=newline
  154. printfr[.L]    <text>,reg    - write formatted register contents
  155. printfv[.L]    <text>,variable    - write formatted variable contents
  156. printfl[.L]    <text>,reglist    - write formatted register list contents
  157.               you can supply number of registers you have
  158.               passed as the 3rd parameter, it will simplify
  159.               the code generated by this macro
  160. err    <text>        - write text and exit with error return code
  161. doserr    <text>        - write text + dos error text and exit
  162. errc.condition    <text>        - if <condition> is false, write text and exit
  163.  
  164. ### NOTES ###
  165.  
  166.    If you define the _GlobVec symbol before startup macro, the startup code
  167. will use pointer to global vector passed in A2.  This is automatically done
  168. by the system, but not by most debuggers, therefore programs compiled with
  169. this option are hardly debuggable unless you specify the DEBUG option.
  170.  
  171.    Some debuggers set false stderr stream when running debugged program.
  172. This is the reason why start/clistart macros set stderr to stdout if DEBUG
  173. is defined.
  174.  
  175.    Some macros mentioned above store the text data into special text hunk.
  176. This produces many relocatable references or causes loss of one register
  177. (usually A4). There are two solutions of this problem:
  178.  
  179.     (1) Use linker to join the hunks. Very good idea, but some compilers don't
  180.         support creation of 16-bit PC-relative references to external symbols.
  181.  
  182.     (2) When doing final compilation of the program, set the GATHERTX symbol
  183.         before calling the start macro. Then run TExtract to extract contents
  184.         of your text hunk to T:TextHunk.i. Compile again with TEXTRACT symbol
  185.         defined (and GATHERTX undefined). The texts will be appended after
  186.         the finish macro and all references done using GETA, TLEA or DTL will
  187.         be PC-relative. These symbols _must_ be defined before SSMac.h
  188.         is included.
  189.