home *** CD-ROM | disk | FTP | other *** search
/ Hall of Fame / HallofFameCDROM.cdr / proglc / tnylib.lzh / TLBMAC.DOC < prev    next >
Encoding:
Text File  |  1987-02-25  |  17.1 KB  |  453 lines
  1.              MAKING ASSEMBLER CODE PORTABLE
  2.  
  3.   Tinylib uses compiler-specific "include" files to take care of all the
  4. differences from one compiler's requirements to another.  These files provide
  5. standardized macros to generate ASM code that meets a specific compiler's
  6. coding conventions.  Separate include files for each compiler, and for each
  7. memory model within any compiler that permits a choice, are required.  At
  8. present, include files for C86 V1.33 (small model), and for Aztec C V3.40
  9. (large model) are provided.
  10.  
  11.   Each file is a macro library.  The one to be used should be copied with the
  12. name "COMPILER.INC".  Each separate module source file in the Tinylib package
  13. begins with the directive "include compiler.inc", and makes extensive use of
  14. these macro facilities to accomodate global-symbol name conventions, memory
  15. models, storage allocation and reference, subroutine calling, and so forth.
  16. The standard macros defined, their parameters (if any), and their actions are
  17. described in the following paragraphs.
  18.  
  19.                 Macro Name: ttl
  20.              Parameters: modnam, vrsn, date, auth
  21.   Defines module name, title line, and revision status for the module.
  22. Required as first macro in each module.
  23.  
  24.  
  25.                    Macro Name: dseg
  26.                 (no parameters)
  27.   Defines start of data segment, and establishes compiler-specific segment-name
  28. or group-name.    Required in each module even if data segment is not used.
  29.  
  30.  
  31.                   Macro Name: exterr
  32.                 (no parameters)
  33.   Declares global error value symbol (as external).  Actual symbol used depends
  34. on compiler's conventions.  See also <moverr>, <geterr>, and <saverr>.
  35.  
  36.  
  37.                   Macro Name: defptr
  38.                   Parameters: ptrnam
  39.   Defines <ptrnam> as a global symbol and reserves space to store a pointer
  40. value.    May modify actual symbol as required by compiler conventions.  Defines
  41. symbol as a WORD for small or program model, or as a DWORD for large or data
  42. model.
  43.  
  44.  
  45.                    Macro Name: extv
  46.                 Parameters: vname, type
  47.   Defines <vname> as a global symbol external to the current module.  May
  48. modify actual symbol as required by compiler conventions.  Defines symbol type
  49. as <type>; no checks of <type> are made.  Can be used for CODE or DATA.
  50.  
  51.  
  52.                   Macro Name: glblvl
  53.                    Parameters: list
  54.   Permits several global symbols to be defined on one line of the source file.
  55. Parameter <list> is a list of parameter sets for macro <glblv>.  Invokes
  56. <glblv> with first set as parameters, repeating until <list> is empty.
  57.  
  58.  
  59.                    Macro Name: glblv
  60.              Parameters: vname, type, val
  61.   Defines <vname> as a global symbol.  May modify actual symbol as required by
  62. compiler conventions.  Defines symbol to be of type defined by <type>,
  63. initialized to <val>.
  64.  
  65.     Valid Types:    <byte>    produces DB definition
  66.             <word>    produces DW definition
  67.             <dword> produces DD definition
  68.     No other symbols may appear as the <type>.
  69.  
  70.  
  71.                    Macro Name: cseg
  72.                 (no parameters)
  73.   Defines end of data segment and start of code segment, and establishes
  74. compiler-specific segment-name or group-name.  Required in each module even if
  75. code segment is not used.
  76.  
  77.                    Macro Name: xtfs
  78.                    Parameters: list
  79.   Permits several external functions to be defined on one line of the source
  80. file.  Parameter <list> is a list of parameters for macro <extf>.  Invokes
  81. <extf> with first parameter, repeating until <list> is empty.
  82.  
  83.  
  84.                    Macro Name: extf
  85.                    Parameters: fname
  86.   Defines <fname> as a code-relative symbol external to the current module.
  87. Type (NEAR or FAR) is compiler-dependent and is automatically included.  Symbol
  88. may be modified to comply with compiler conventions.
  89.  
  90.  
  91.                   Macro Name: moverr
  92.                 Parameters: val
  93.   Sets global error value from <val> (which may be a register or a symbol
  94. reference).  Actual symbol used for global error value depends on compiler's
  95. conventions.  See <exterr>.
  96.  
  97.  
  98.                   Macro Name: geterr
  99.                 Parameters: val
  100.   Gets global error value into <val> (which may be a register or a symbol
  101. reference.  Actual symbol used for global error value depends on compiler's
  102. conventions.  See <exterr>.
  103.  
  104.  
  105.                   Macro Name: saverr
  106.                 (no parameters)
  107.   Copies global error value into stream table, assuming SI points to it.
  108. Actual symbol used for global error value depends on compiler's conventions.
  109. See <exterr>.
  110.  
  111.  
  112.                   Macro Name: procdef
  113.                 Parameters: pname, args
  114.   Defines a global procedure with name <pname>.  Symbol may be modified to
  115. conform to compiler's conventions.  Saves BP and defines symbols to reference
  116. arguments passed to procedure as specified by the <args> list.    Establishes
  117. PROC block which must be closed with <pend>.  Note that these procedures may
  118. NOT be nested.
  119.  
  120.  
  121.                    Macro Name: dargs
  122.                    Parameters: list
  123.   Interfaces procedure-defining macros <procdef> and <statdef> to the <darg>
  124. macro.    Parameter <list> is a list of parameter sets for macro <darg>.    Invokes
  125. <darg> with first parameter set, repeating until <list> is empty.
  126.  
  127.  
  128.                    Macro Name: darg
  129.                 Parameters: aname, type
  130.   Equates <aname> to offset (BP-relative) for argument on stack.  For strongly
  131. typed assemblers such as MASM, defines symbol same as <aname> with "_v"
  132. suffixed to be actual offset value, and defines <aname> as typed BP reference.
  133. Automatically maintains offset values using argument size obtained from <type>
  134. parameter.
  135.  
  136.     Valid Types:    <byte>      - 1 BYTE
  137.             <word>      - 1 WORD
  138.             <dword>   - 2 WORDs for "long" or "float" data
  139.             <cdouble> - 4 WORDs for "double" data
  140.             <ptr>      - 2 or 4 WORDs for data pointer
  141.             <fptr>      - 2 or 4 WORDs for function pointer
  142.     No other strings are valid for <type>.
  143.  
  144.  
  145.                    Macro Name: locs
  146.                    Parameters: list
  147.   Terminates set of <dclv> declarations and adjusts SP value to reserve local
  148. variable space.  Parameter <list> is a list of parameter sets for <dclv>.  This
  149. macro should be used only once per procedure definition.
  150.  
  151.  
  152.                    Macro Name: dclv
  153.              Parameters: lvnm, type, asiz
  154.   Defines <lvnm> as a local automatic (BP-relative) variable with size
  155. determined by <type>.  If <type> indicates an array, <asiz> is size of array;
  156. else <asiz> is ignored.  Same typing considerations discussed for <darg> apply
  157. here; major difference between <darg> and <dclv> is the sign of the offset
  158. values.
  159.  
  160.     Valid Types:    <byte>      - 1 BYTE
  161.             <word>      - 1 WORD
  162.             <dword>   - 2 WORDs for "long" or "float" data
  163.             <cdouble> - 4 WORDs for "double" data
  164.             <ptr>      - 2 or 4 WORDs for data pointer
  165.             <fptr>      - 2 or 4 WORDs for function pointer
  166.             <baray>   - array of BYTEs
  167.             <iaray>   - array of WORDs
  168.     No other strings are valid for <type>.
  169.  
  170.  
  171.                    Macro Name: alias
  172.                Parameters: pname, altnam
  173.   Declares <altnam> to be equivalent to <pname>; used to provide alternate name
  174. for procedures such as "strchr()" and "index()".  May modify actual symbol to
  175. conform to compiler's global-symbol conventions.
  176.  
  177.  
  178.                   Macro Name: entrdef
  179.                    Parameters: pname
  180.   Declares <pname> as an alternate entry point for a global procedure,
  181. accepting the same list of arguments declared with macro <procdef> at the
  182. procedure's primary definition.  May modify actual symbol to conform to
  183. compiler's global-symbol conventions.
  184.  
  185.  
  186.                   Macro Name: statdef
  187.                 Parameters: pname, args
  188.   Local equivalent of <procdef>.  Defines a static (local) procedure with name
  189. <pname>.  Saves BP and defines symbols to reference arguments passed to
  190. procedure as specified by the <args> list.  Establishes PROC block which must
  191. be closed with <iend>.    Note that these procedures may NOT be nested.
  192.  
  193.  
  194.                  Macro Name: internal
  195.                    Parameters: pname
  196.   Defines a static (local) procedure with name <pname> that has no arguments.
  197. Establishes PROC block which must be closed with <iend>.  Note that these
  198. procedures may NOT be nested.
  199.  
  200.  
  201.                   Macro Name: intrdef
  202.                    Parameters: pname
  203.   Local equivalent of <entrdef>.  Declares <pname> as an alternate entry point
  204. for a local procedure, accepting the same list of arguments declared with macro
  205. <statdef> at the procedure's primary definition.
  206.  
  207.  
  208.                   Macro Name: callit
  209.                 Parameters: pname, args
  210.   Generates complete call sequence to global procedure <pname>.  Uses
  211. <pushargs> macro to push argument values listed in <args> onto stack, keeping
  212. count of the number of bytes pushed, issues CALL (modifying <pname> as required
  213. by compiler's conventions), and flushes stack upon return.  Note that <args>
  214. list is processed left to right while C conventions usually require
  215. reverse-order stacking; thus arguments must appear in the REVERSE of their
  216. normal sequence in the <args> list.
  217.  
  218.  
  219.                  Macro Name: pushargs
  220.                    Parameters: list
  221.   Interfaces procedure-calling macros such as <callit> to <pusharg>.  Parameter
  222. <list> is a list of parameter sets for macro <pusharg>.  Invokes <pusharg> with
  223. first parameter set, repeating until <list> is empty.  Thus the LAST parameter
  224. set in the <list> will be at the lowest stack address when this macro
  225. terminates.
  226.  
  227.  
  228.                   Macro Name: pusharg
  229.             Parameters: varib, type, segref
  230.   Pushes word or words specified by <varib>, <type>, and <segref> onto stack as
  231. arguments for a call to another procedure.  Number of words pushed is specified
  232. by parameter <type>.  Parameter <segref> is used only when the <type> requires
  233. a segment reference.  Maintains count of number of bytes pushed for use in
  234. flushing stack later.
  235.  
  236.     Valid Types:    <byte>    pushes 2 bytes onto stack from memory
  237.                 location <varib>.
  238.             <word>    pushes 2 bytes onto stack from memory
  239.                 location <varib>.
  240.             <reg>    pushes register <varib> onto stack.
  241.                 Must be 16-bit register; counts 2 bytes.
  242.             <preg>    pushes <segref> onto stack, followed by
  243.                 pointer register <varib>.  If <segref> is
  244.                 omitted, uses default value for <varib>.
  245.                 Counts 4 bytes.
  246.             <dword> pushes 4 bytes starting at memory location
  247.                 <varib> onto stack, by words.  Word at
  248.                 <varib>+2 is pushed first.
  249.             <cdouble> pushes 8 bytes starting at memory
  250.                 location <varib> onto stack, by words.
  251.                 Word at <varib>+6 is pushed first, then
  252.                 <varib>+4, <varib>+2, and <varib>.
  253.             <ptr>    pushes content of pointer <varib> onto
  254.                 stack.    Counts 2 bytes in small or program
  255.                 model, 4 in data or large.
  256.             <fptr>    pushes address of memory reference <varib>
  257.                 onto stack.  Counts 2 bytes in small or
  258.                 data model, 4 in program or large.
  259.                 Segment address is pushed first, in large
  260.                 or program model, followed by offset.
  261.     No other strings are valid for <type>.
  262.  
  263.  
  264.                   Macro Name: pushptr
  265.                   Parameters: pointer
  266.   For data or large model, pushes content of memory reference <pointer>[2] to
  267. the stack.  For all models, pushes content of <pointer> to stack.
  268.  
  269.  
  270.                   Macro Name: popptr
  271.                   Parameters: pointer
  272.   Inverse of macro <pushptr>; pops from stack into memory reference <pointer>
  273. for all models.  For data or large model, then pops from stack into
  274. <pointer>[2].
  275.  
  276.  
  277.                   Macro Name: pshloc
  278.                    Parameters: vnam
  279.   Pushes content of local variable <vnam> onto stack.  Regardless of type
  280. declared for <vnam>, this macro references it as a WORD.
  281.  
  282.  
  283.                   Macro Name: psharg
  284.                    Parameters: anam
  285.   Pushes content of argument <anam> onto stack.  Like <pshloc>, the argument is
  286. referenced as a WORD.
  287.  
  288.  
  289.                   Macro Name: pushreg
  290.                 (no parameters)
  291.   Generates PUSH DI/PUSH SI and sets HAVEREG flag to indicate that registers
  292. have been saved.
  293.  
  294.  
  295.                   Macro Name: popreg
  296.                 (no parameters)
  297.   If HAVEREG is clear, does nothing.  If set, generates POP SI/POP DI and
  298. clears HAVEREG flag to indicate that registers have been restored.
  299.  
  300.  
  301.                   Macro Name: pushds
  302.                 (no parameters)
  303.   In small or program model, does nothing.  In large or data model, generates
  304. PUSH DS and sets HAVEDS flag to indicate that DS has been saved.
  305.  
  306.  
  307.                    Macro Name: popds
  308.                 (no parameters)
  309.   In small or program model, or if HAVEDS flag is clear, does nothing.    In
  310. large or data model, if HAVEDS flag is set, generates POP DS and clears HAVEDS
  311. flag to indicate that DS has been restored.
  312.  
  313.  
  314.                    Macro Name: ldptr
  315.                Parameters: dest, argname, segref
  316.   Loads register <dest> from memory reference <argname>.  In small or program
  317. model, generates a MOV <dest>,<argname> instruction and the <segref> parameter
  318. is ignored.
  319.   In data or large models the macro is much more complex:  If <segreg> is "DS",
  320. a "LDS" instruction is generated.  If it is "ES", a "LES" instruction results.
  321. If <segreg> is omitted, a "LDS" is generated for <dest> of "SI", "LES" for
  322. "DI", and any other value for the <dest> parameter produces an error message.
  323. If <segreg> is present and is any other value, a pair of MOV instructions are
  324. generated.  The first loads <dest> from <argname> and the second loads <segref>
  325. from <argname>[2].
  326.  
  327.  
  328.                    Macro Name: svptr
  329.                Parameters: dest, argname, segref
  330.   Stores an arg pointer from registers <segref>:<dest> into 4 bytes of memory
  331. starting at <argname>, in standard offset:segment format, for data or large
  332. models.  If <segref> is missing, determines default value by rules similar to
  333. those described for macro <ldptr>.  For small or program model, ignores
  334. <segref> and stores register <dest> in WORD at <argname>.
  335.  
  336.  
  337.                   Macro Name: setptr
  338.             Parameters: ptrnam, sym, segref
  339.   Sets global, static, or auto memory location <ptrnam> to point to address
  340. <segref>:<sym>.  In small or program memory model, parameter <segref> is
  341. ignored; if omitted large or data model macro will assign default.  Note that
  342. AX is destroyed.
  343.  
  344.  
  345.                  Macro Name: ptrcpyinc
  346.                  Parameters: from, to
  347.   Copies value pointed to by parameter <from>, into global, static, or auto
  348. memory location <to>, and post-increments pointer <from>.  Uses register AX
  349. (and DX in the large or data model) for the transfer; fetches with macro <gwi>.
  350.  
  351.  
  352.                  Macro Name: extraseg
  353.                 (no parameters)
  354.   Forces ES to same value as DS, by PUSH/POP sequence.    No other registers or
  355. flags are affected.
  356.  
  357.  
  358.                 Macro Name: gci
  359.                   Parameters: ptrnam
  360.   Fetches single byte pointed to by <ptrnam> into AL register and
  361. post-increments <ptrnam>.  Uses the <ldptr> macro to load SI register from
  362. <ptrnam>, LODSB to fetch byte and increment SI, and <svptr> macro to store
  363. incremented register back into <ptrnam>.  Use primarily for single- byte
  364. actions; if more than a couple of bytes are to be fetched, separate <ldptr>,
  365. LODSB, and <svptr> calls have much less overhead.
  366.  
  367.  
  368.                 Macro Name: pci
  369.                   Parameters: ptrnam
  370.   Inverse of <gci> macro above.  Stores AL register where <ptrnam> points,
  371. using DI register, and post-increments <ptrnam>.  Same overhead considerations
  372. apply.
  373.  
  374.  
  375.                 Macro Name: gwi
  376.                   Parameters: ptrnam
  377.   Same as <gci> except that it moves a 16-bit word into AX.  All considerations
  378. apply.
  379.  
  380.  
  381.                 Macro Name: pwi
  382.                   Parameters: ptrnam
  383.   Same as <pci> except that it moves a 16-bit word from AX.  All considerations
  384. apply.
  385.  
  386.  
  387.                    Macro Name: caseb
  388.                  Parameters: val, goto
  389.   Compares content of AL with parameter <val>, which may be constant, memory
  390. reference, or register.  If equal, branches to "short label" <goto>.
  391.  
  392.  
  393.                    Macro Name: casew
  394.                  Parameters: val, goto
  395.   Same as <caseb> except compares AX to <val>.
  396.  
  397.  
  398.                   Macro Name: retptrm
  399.                 Parameters: src
  400.   Generates code to return a pointer value in DX:AX.  If CY flag is set when
  401. this code is reached, a NULL pointer value is returned.  If not, the value from
  402. memory location <src> (which may be relative to either BP or DS) is returned in
  403. AX, and that from the following word is returned in DX.  Uses macro <pret> to
  404. generate actual return code.
  405.  
  406.  
  407.                   Macro Name: retptrr
  408.                   Parameters: src,seg
  409.   Generates code to return a pointer value in DX:AX.  If CY flag is set when
  410. this code is reached, a NULL pointer value is returned.  If not, the value from
  411. <src> (which may be a memory reference or a register) is returned in AX, and
  412. that from <seg> is returned in DX.  Uses macro <pret> to generate actual return
  413. code.
  414.  
  415.  
  416.                   Macro Name: retnull
  417.                 (no parameters)
  418.   Generates code to return a NULL value in AX (and DX for large model).  Uses
  419. macro <pret> to generate actual return code.
  420.  
  421.  
  422.                   Macro Name: retyes
  423.                 (no parameters)
  424.   Generates code to return a value of 0001 in AX only.    Uses macro <pret> to
  425. generate actual return code.
  426.  
  427.  
  428.                    Macro Name: pret
  429.                 (no parameters)
  430.   Restores BP and registers, then executes RET.  Note that since <pret> clears
  431. flags that indicate registers have been pushed, it must not be used more than
  432. once per procedure.  Since the other "ret" macros all invoke <pret>, only one
  433. of this group should be used.
  434.  
  435.  
  436.                    Macro Name: iend
  437.                    Parameters: pname
  438.   Ends definition of the static or internal procedure named <pname>.
  439.  
  440.  
  441.                    Macro Name: pend
  442.                    Parameters: pname
  443.   Ends definition of the global procedure named <pname> (as modified by the
  444. macro which began the definition).
  445.  
  446.  
  447.                   Macro Name: finish
  448.                 (no parameters)
  449.   Ends definition of the code segment and the module.  Required for all
  450. modules; must be last line of source file.
  451.  
  452.         ============= end of description =============
  453.