home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource3 / 140_01 / zcasm.doc < prev    next >
Text File  |  1985-03-11  |  7KB  |  137 lines
  1. ZCASM.DOC 
  2.  
  3. Copyright (c) 1984 Brian Waldron, Xerox Corp.
  4. based on CASM.DOC by Leor Zolman
  5.  
  6.  
  7.  
  8. This document describes the ZCASM Assembly language --> CRL-Format Preprocessor
  9. for BDS C 1.5. The original program, CASM.C, has been modified to process ZILOG
  10. mnemonics and  output  short  labels  for  assembly  with  Microsoft's  M80/L80
  11. combination.
  12.  
  13. The files making up the ZCASM package are as follows:
  14.  
  15. ZCASM.DOC    This file
  16. ZCASM.C        Source file for ZCASM program
  17. ZCASM.SUB    Submit file for performing entire conversion of CZM
  18.         file to CRL which looks like this:
  19.  
  20.                 zcasm $1
  21.                 m80 =$1/z
  22.                 l80 $1,$1.crl/n/e
  23.  
  24. You also need:    M80, L80
  25.  
  26. ZCASM  is hereby placed in the public domain with  the  restriction that it may
  27. not be distributed for profit.
  28.  
  29. Description:
  30.  
  31. The only  means  previously  provided to  BDS C users for creating  relocatable
  32. object modules (CRL files)  from  assembly  language  programs  was a painfully
  33. obscure macro  package  (CMAC.LIB)  that  required   Digital  Research's  macro
  34. assembler (MAC.COM) in order to work.  Then  came  CASM, written by Leor Zolman
  35. which greatly simplified  the process.  CASM,  however,  being designed to work
  36. with  DR's standard  assembler (ASM.COM),  only  digests Intel mnemonics.  This
  37. document describes "ZCASM", which is a ZILOG mnemonic version of CASM.
  38.  
  39. ZCASM will read  ZILOG Z80 mnemonics and create  a .MAC file to be processed by
  40. M80. L80 then creates a .CRL file directly without the need for DDT or the SAVE
  41. command.
  42.  
  43. ZCASM takes, as input, an assembly language source file of type ".CZM"(mnemonic
  44. for C Z80  preprocessor for M80) in a format much closer to  "vanilla" assembly
  45. language  than  the bizarre  craziness of CMAC.LIB, and  writes out a .MAC file
  46. which  may  then  be assembled  by  Microsoft's  M80/L80  combination.    ZCASM
  47. automatically recognizes which assembly language instructions  need  relocation
  48. parameters and inserts the appropriate pseudo-operations and extra opcodes into
  49. the output file to  cause  that  file to  properly  assemble  directly into CRL
  50. format. In addition, some  rudimentary  logic  checking is done; doubly-defined
  51. and/or undefined labels are detected and reported, with the feature of allowing
  52. similarly-named labels to exist in different functions.
  53.  
  54. The pseudo-operations that  ZCASM recognizes as special control commands within
  55. a .CZM file are as follows:
  56.  
  57. FUNCTION <name>      There is no need to specify a directory of included functions
  58.           at the start of a .CZM file.  Each  function  must begin with
  59.           "function" pseudo-op, where <name> is  the  name that will be
  60.           used for the  function in the .CRL file directory.   No other
  61.           information should appear on this line.
  62.  
  63. EXTERNAL <list>      If a function calls other C or  assembly-coded  functions, an
  64.           "external" pseudo-op naming these other functions must follow
  65.           immediately after the "function" op.   One or more  names may
  66.           appear in the list, and the list may be spread  over  as many
  67.           "external" lines as  necessary.   Note  that for the  current
  68.           version  of  BDS C,  only   function  names   may  appear  in
  69.           "external"  lines;  data names  (e.g. for external  variables
  70.           defined  in  C  programs)  cannot  be  placed  in  "external"
  71.           statements.
  72.  
  73. ENDFUNC
  74. ENDFUNCTION      This op (both forms are equivalent) must appear after the end
  75.           of  the  code  for  a  particular  function.  The name of the
  76.           function need not be given as an operand.  The three  pseudo-
  77.           ops just listed are the ONLY  pseudo-ops  that need to appear
  78.           among the  assembly  language instructions of a ".CZM"  file,
  79.           and at no time do the assembly instruction themselves need to
  80.           be altered for relocation, as was the case with CMAC.LIB.
  81.            
  82. INCLUDE <filename>
  83. INCLUDE "filename" This op causes the named file to be inserted at the  current
  84.           line of the output file. If the filename is enclosed in angle
  85.           brackets (i.e., <filename>)  then a  default  user  area  and
  86.           logical drive  are assumed  to contain the  named  file  (the
  87.           specific  defaults  for  your  system may  be  customized  by
  88.           changing the appropriate defines in ZCASM.C).  If the name is
  89.           enclosed in quotes, than the current  drive and user area are
  90.           searched. Note that you'll  usually  want to include the file
  91.           BDS.LIB at the start of your  .CZM file  (see # 7, additional
  92.           notes and bugs), so that  names  of routines  in the run-time
  93.           package  are  recognized  by  ZCASM  and  not  interpreted as
  94.           undefined local forward references, which would  cause  ZCASM
  95.           to  generate  relocation  parameters  for those  instructions
  96.           having run-time package routine names as operands.  Note that
  97.           the pseudo-op MACLIB is equivalent to INCLUDE and may be used
  98.           instead.
  99.  
  100. Additional notes and bugs:  
  101.  
  102. 0.    If a label  appears  on  an instruction, it MUST begin in column one of
  103.     the line.  If a label does  not  begin  in  column one,  ZCASM will not
  104.     recognize it as a label and relocation will not be handled correctly.
  105.  
  106. 1.    Forward  references  to  EQUated symbols in executable instructions are
  107.     not allowed, although forward references to relocatable symbols are OK.
  108.     The reason  for  this is that ZCASM is a one-pass preprocessor, and any
  109.     time a previously  unknown  symbol is encountered  in  an  instruction,
  110.     ZCASM  assumes  that  symbol is relocatable and  generates a relocation
  111.     parameter for the instruction.
  112.  
  113. 2.    INCLUDE and MACLIB only work for one level of inclusion.
  114.  
  115. 3.    When a relocatable value is specified in a "DEFW" op, then it  must  be
  116.     the  ONLY  value  given  in  that  particular  DEFW statement,  or else
  117.     relocation will not be properly handled.
  118.  
  119. 4.    Characters used in symbol names should  be  restricted  to alphanumeric
  120.     characters; the dollar sign ($) is also allowed, but may  conflict with
  121.     labels generated by ZCASM.
  122.  
  123. 5.    The ZCASM.SUB  submit  file may be used to perform the entire procedure
  124.     of converting  a .CZM file to a .CRL file.  For a file named "FOO.CZM",
  125.     just say:
  126.  
  127.     submit zcasm foo
  128.  
  129. 6.    You should  include  the  pseudo-op  ASEG at the beginning of your .CZM
  130.     file for M80 to properly assemble the code. If you also place a .Z80 at
  131.     the top of the file, the /z switch in ZCASM.SUB may be omitted.
  132.  
  133. 7.    When #INCLUDEing BDS.LIB, use a version with all DS, DB or DW's removed
  134.     as this  can  cause problems  with the assembled code.  I use something
  135.     called RUNDEFS.LIB which  contains EQUates extracted or calculated from
  136.     BDS.LIB.
  137.