home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / bdsc-1 / casm.dqc / CASM.DOC
Encoding:
Text File  |  1985-02-10  |  8.4 KB  |  195 lines
  1.  
  2.  
  3.             The CASM.C Assembly-language-to-CRL-Format Preprocessor
  4.                                 For BDS C v1.46
  5.                                  March 3, 1982
  6.  
  7.                                   Leor Zolman
  8.                                   BD Software
  9.                                 33 Lothrop st.
  10.                         Brighton, Massachussetts 02135
  11.  
  12.  
  13. The files making up the CASM package are as follows:
  14.  
  15. CASM.C         Source file for CASM program
  16. CASM.SUB       Submit file for performing entire conversion of CSM file to CRL
  17. CASM.DOC       This file
  18. USERCODE.C,    Library for taking user area prefixes on filenames
  19. USERCODE.CRL                          for input files (optional).
  20.  
  21. Also needed:
  22.  
  23. ASM.COM
  24. DDT.COM (or SID.COM)
  25.  
  26. Description:
  27. ------------
  28.  
  29.      The only means previously provided to BDS C users for creating relocatable
  30. object  modules  (CRL  files)  from  assembly language programs was a painfully
  31. obscure  macro  package  (CMAC.LIB)  that  required  Digital  Research's  macro
  32. assembler (MAC.COM) in order to work.  This  was especially bad because MAC, if
  33. not already owned, cost almost as much as BDS  C  to  purchase.  This  document
  34. describes the program "CASM", which I am placing in the public domain. CASM  is
  35. a  preprocessor  that takes, as input, an assembly language source file of type
  36. ".CSM" (mnemonic for  C aSseMbly language) in a format much closer to "vanilla"
  37. assembly language than  the  bizarre  craziness  of CMAC.LIB, and writes out an
  38. ".ASM" file which may then be assembled by the standard,  FREE,  CP/M assembler
  39. (ASM.COM).  CASM  automatically recognizes which assembly language instructions
  40. require relocation parameters and inserts the appropriate pseudo-operations and
  41. extra opcodes into  the  output  file  to  cause that file to properly assemble
  42. directly  into  CRL  format. In addition, some  rudimentary  logic  checks  are
  43. performed; doubly-defined  and/or  undefined  labels are detected and reported,
  44. with  the  feature of allowing similarly-named labels  to  exist  in  different
  45. functions.  
  46.  
  47.      The pseudo-operations  that  CASM  recognizes  as special control commands
  48. within a .CSM file are as follows:  
  49.  
  50.  
  51.  
  52.  
  53. FUNCTION <name>          There is no need to specify  a  directory  of included
  54.                          functions  at the start of a .CSM file. Each  function
  55.                          must begin with  "function" pseudo-op, where <name> is
  56.                          the name that will  be  used  for  the function in the
  57.                          .CRL  file  directory.  No  other  information  should
  58.                          appear on this line.  
  59.  
  60.  
  61. EXTERNAL <list>          If   a   function  calls  other  C  or  assembly-coded
  62.                          functions,  an "external" pseudo-op naming these other
  63.                          functions must follow immediately after the "function"
  64.                                         1
  65.  
  66.  
  67.                          op.  One or more names may appear in the list, and the
  68.                          list may be spread  over  as  many "external" lines as
  69.                          necessary. Note that for the current version of BDS C,
  70.                          only function names may appear  in  "external"  lines;
  71.                          data  names (e.g. for external variables defined in  C
  72.                          programs)  cannot  be placed in "external" statements.
  73.  
  74.  
  75. ENDFUNC                          
  76. (or) ENDFUNCTION         This op (both forms  are equivalent) must appear after
  77.                          the end of the code for  a  particular  function.  The
  78.                          name  of the function need not be given as an operand.
  79.                          The  three   pseudo-ops   just  listed  are  the  ONLY
  80.                          pseudo-ops  that  need to appear  among  the  assembly
  81.                          language instructions of a ".CSM" file, and at no time
  82.                          do  the assembly instruction  themselves  need  to  be
  83.                          altered for relocation, as was the case with CMAC.LIB.
  84.  
  85.  
  86. INCLUDE <filename>                     
  87. (or) INCLUDE "filename"  This  op  causes  the named file to be inserted at the
  88.                          current line of the  output  file.  If the filename is
  89.                          enclosed in angle brackets (i.e., <filename>)  then  a
  90.                          default  user  area  and  logical drive are assumed to
  91.                          contain the named file (the specific defaults for your
  92.                          system may be custimzed by  changing  the  appropriate
  93.                           defines  in  CASM.C).  If  the  name  is enclosed  in
  94.                          quotes,  than  the  current  drive and user  area  are
  95.                          searched. Note that you'll usually want to include the
  96.                          file BDS.LIB at the start of your  .CSM  file, so that
  97.                          names   of  routines  in  the  run-time  package   are
  98.                          recognized  by  CASM  and not interpreted as undefined
  99.                          local forward references,  which  would  cause CASM to
  100.                          generate  relocation parameters for those instructions
  101.                          having run-time  package  routine  names  as operands.
  102.                          Note  that  the  pseudo-op  MACLIB  is  equivalent  to
  103.                          INCLUDE and may be used instead.  
  104.  
  105.  
  106. Additional notes and bugs:  
  107.  
  108. 0. If  a  label appears on an instruction, it MUST begin in column one  of  the
  109.    line. If a label does not begin in column one, CASM will not recognize it as
  110.    a label and relocation will not be handled correctly.  
  111.  
  112. 1. Forward  references  to  EQUated  symbols in executable instructions are not
  113.    allowed, although forward references  to  relocatable  symbols  are OK.  The
  114.    reason  for  this  is that CASM is a one-pass preprocessor, and any  time  a
  115.    previously unknown symbol  is  encountered  in  an instruction, CASM assumes
  116.    that  symbol  is relocatable and generates a relocation  parameter  for  the
  117.    instruction.  
  118.  
  119. 2. INCLUDE and MACLIB only work for one level of inclusion.  
  120.  
  121. 3. When a relocatable value needs to be specified in a "DW" op, then it must be
  122.    the ONLY value  given  in  that  particular DW statement, or else relocation
  123.    will not be properly handled.  
  124.  
  125. 4. Characters  used  in  symbol  names should  be  restricted  to  alphanumeric
  126.    characters; the dollar sign ($)  is  also  allowed,  but  might  lead  to  a
  127.    conflict with labels generated by CASM.  
  128.  
  129.                                         2
  130.  
  131.  
  132. 5. The  .HEX file produced by ASM after assembling the output of CASM cannot be
  133.    converted  into a binary file by using the LOAD.COM command; instead, DDT or
  134.    SID must be  used  to  read  the  file into memory, and then the CP/M "SAVE"
  135.    command must be issued to save the  file as a .CRL file. CASM inserts a line
  136.    into the ASM file ending in the character  sequence  "!.",  specifically  so
  137.    that  the  line  will  be flagged as an error. The user may then look at the
  138.    value printed out at the left margin to see exactly how many 256-byte blocks
  139.    need to be saved; this is the value to be used with the "SAVE" command.  
  140.  
  141.    The reason that "LOAD" cannot  be  used  is  that  CASM puts out the code to
  142.    generate the CRL File directory at the END of the ASM file, using ORG to set
  143.    the  location counter back to the base of the TPA, and  the  "LOAD"  command
  144.    aborts with the cryptic message "INVERTED LOAD ADDRESS" when out-of-sequence
  145.    data like  that  is  encountered.  Rather than require CASM to write out the
  146.    directory into a new file and append the entire previous output onto the end
  147.    of the directory, I require the user  to have to enter a SAVE command.  What
  148.    the heck; you'd have to rename the file anyway if it were LOADed, right?  
  149.  
  150. 6. The CASM.SUB submit file may be used to  perform  the  entire  procedure  of
  151.    converting a .CSM file to a .CRL file. For a file named "FOO.CSM", just say:
  152.        submit casm foo
  153.  
  154.    and enter the "SAVE" command just the way says when all is done.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                         3
  195.