home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug103.arc / NOTES < prev    next >
Encoding:
Text File  |  1979-12-31  |  16.4 KB  |  397 lines
  1.     (7-10-85)                 Small-Mac User Notes                page 1
  2.  
  3.     
  4.     COPYRIGHT NOTICE
  5.     
  6.     Small-Mac Assembler: Copyright 1985 J. E. Hendrix
  7.     
  8.         This is copyrighted material.  All rights are reserved.  Use  it
  9.     only in accordance with the terms set forth in the registration form
  10.     (file REGISTER).
  11.     
  12.     THE OBJECT DISKETTE
  13.     
  14.     The  object  diskette  contains executable versions of the Small-Mac
  15.     programs, and a library for use when linking Small-C programs.  Also
  16.     included is the source code for three of the modules in that library
  17.     which have been revised for use with the Small-Mac software  instead
  18.     of the Microsoft package which was originally used with Small-C.
  19.     
  20.     These  programs  run under CP/M 2.2 (and later versions) and require
  21.     56K bytes of RAM. The following files are on the diskette:
  22.     
  23.       NOTES     these notes
  24.       MAC       synopsys of Small-Mac package
  25.       REGISTER  Small-Mac user registration form
  26.       HISTORY   history of Small-Mac quirks, and revisions
  27.       MAC.COM   executable macro assembler (configured for the 8080 CPU)
  28.       LNK.COM   executable linkage editor
  29.       LGO.COM   executable load-and-go loader
  30.       LIB.COM   executable library manager
  31.       CMIT.COM  executable configuration utility
  32.       DREL.COM  executable relocatable-file dump utility
  33.       C.LIB     Small-C standard library rivised for Small-Mac
  34.       C.NDX     index to C.LIB
  35.       C.LST     list of C.LIB modules
  36.       8080.MIT  8080 machine-instruction-table source file
  37.       Z80.MIT   Z80 machine-instruction-table source file
  38.       ------>   revised Small-C library sources
  39.                     CALL.MAC  END.MAC   LINK.MAC  
  40.     
  41.     Ordinarily, you will need ready access only to MAC.COM, LNK.COM, and
  42.     (if you are assembling Small-C programs) C.LIB and C.NDX.  Small-Mac
  43.     libraries  consist of a pair of files, the library proper (.LIB) and
  44.     its index (.NDX).  Take care to always keep  these  files  together.
  45.     The  library  named  C  must  be  searched  whenever linking Small-C
  46.     programs.  It replaces the corresponding library, CLIB.REL,  on  the
  47.     Small-C  distribution  diskette  which  is  used  with the Microsoft
  48.     linker.  CALL, END, and LINK  are  the  only  modules  which  differ
  49.     between these libraries.
  50.     
  51.     THE SOURCE DISKETTE
  52.     
  53.  
  54.  
  55.     
  56. è    (7-10-85)                Small-Mac User Notes                 page 2
  57.  
  58.     This  diskette  contains the source code for the Small-Mac assembler
  59.     package  as  it  is  implemented  to  run  under CP/M 2.2 (and later
  60.     versions).  The following files are on the diskette:
  61.     
  62.         NOTICE.H  version message, and copyright notice
  63.         STDIO.H   standard i/o header
  64.         M.LIB     Small-Mac library (used when linking Small-Mac programs)
  65.         M.NDX     index to M.LIB
  66.         M.LST     list of M.LIB modules
  67.         MAC.H     header for MAC, MAC2, MAC3, and CMIT
  68.         EXT.H     header for MAC2 and MAC3 external references
  69.         MIT.H     header for machine instruction table functions
  70.         REL.H     header for .REL file functions
  71.         MAC.C     assembler source part 1
  72.         MAC2.C    assembler source part 2
  73.         MAC3.C    assembler source part 3
  74.         LNK.C     linkage editor source
  75.         LGO.C     load-and-go loader source
  76.         LIB.C     library manager source
  77.         CMIT.C    configuration utility source
  78.         DREL.C    dump utility source
  79.         ------>   Small-Mac library sources
  80.                       EXTEND.C  FILE.C    GETREL.C  PUTREL.C
  81.                       SEEREL.C  MESS.C    SCAN.C    WAIT.C
  82.                       INT.C     MIT.C     REL.C     REQ.C
  83.     
  84.     USING THE ASSEMBLER
  85.     
  86.     The assembler translates 8080 (or optionally Z80) assembly  language
  87.     into the  Microsoft  relocatable format.  The input has a free field
  88.     format with fields appearing in the following order on each line:
  89.     
  90.           label/symbol   operation   operand   comment
  91.     
  92.     Each field is optional.  Fields are separated by white space, except
  93.     that comments are prefixed by a semicolon (;).
  94.     
  95.     Small-Mac   supports   the    following    assembler    instructions
  96.     (pseudo-ops):
  97.     
  98.     [label] DW  expr[,expr[,...]]        define words
  99.     [label] DB  expr[,expr[,...]]        define bytes
  100.     [label] DS  expr                     define storage
  101.     [label] EXT symbol[,symbol[,;;;]]    declare external references
  102.     symbol  SET expr                     set symbol to expr
  103.     symbol  EQU expr                     equate symbol to expr
  104.     [label] ORG expr                     set location counter to expr
  105.     [label] END [expr]                   end of source file
  106.                                          (expr gives starting address)
  107.     symbol  MACRO                        begin a macro definition
  108.             ENDM                         end a macro definition
  109.     [label] macroname [par][,][par]...   call (expand) the named macro
  110.     
  111. è
  112.  
  113.     
  114.     (7-10-85)                Small-Mac User Notes                 page 3
  115.  
  116.     Labels must  be  terminated  with one or two colons (:).  Two colons
  117.     declares the label as an entry point.  Non-label symbols must NOT be
  118.     terminated with  a colon.  Symbols appearing in an expression (expr)
  119.     may be terminated with two pound signs (#); this declares the symbol
  120.     as an external reference.
  121.     
  122.     Symbols (including labels) may contain letters, digits, and  any  of
  123.     the special  characters  "_",  ".", "$", "?", "@".  Symbols must NOT
  124.     begin with a digit.  Upper and lower  case  letters  are  considered
  125.     equivalent in symbols and operation codes (mnemonics).
  126.     
  127.     Expressions consist of numbers, symbols, operators, and parentheses.
  128.     Numbers are assumed to be decimal unless followed immediately by one
  129.     of the following letters:
  130.     
  131.               O or Q     specifies octal
  132.               H          specifies hexadecimal
  133.     
  134.     Symbols  in  an  expression  must  either be defined elsewhere or be
  135.     terminated with a pair of pound signs.    Expression  operators  are
  136.     exactly  those  of  the  C  language  and follow the same precedence
  137.     rules.  Parentheses may be used to control  grouping.    The  dollar
  138.     sign  "$" may be used in an expression to stand for the value of the
  139.     location counter at the beginning of the current instruction.
  140.     
  141.     Expressions used in  EQU  and  SET  directives  should  not  contain
  142.     forward references.      That  is  any  symbols  appearing  in  such
  143.     expressions should have been defined previously in the program.
  144.     
  145.     Macro definitions do not take dummy parameters.  Simply place ?1  in
  146.     the  body of the macro where the first actual parameter is to go, ?2
  147.     for the second and ?0 for the 10th and final one.  A maximum  of  10
  148.     parameters are  allowed.    Actual  parameters  in  a macro call are
  149.     identified by position and are  separated  by  commas.    Successive
  150.     commas  or  absent  trailing parameters produce a null substitution;
  151.     i.e., the substitution sentinels (e.g.  ?3)  corresponding  to  null
  152.     parameters are squeezed out of the expanded text.  If a ? is desired
  153.     in the  expanded  text,  code  ??  in  the  macro  body.   Quotes or
  154.     apostrophes may delimit an actual parameter containing spaces.    An
  155.     occurrence  of the delimiter within the string is achieved by giving
  156.     two successive delimiters.  Ten labels which are local to each macro
  157.     expansion may be specified as @0 through @9.  The first such  label,
  158.     and  its  references,  will  appear  in the expanded text as @1, the
  159.     second as @2, etc.  The sequence continues  to  increase  throughout
  160.     the  program  so  that  every  such  label,  and  its references, is
  161.     guaranteed to be unique.  This avoids "redundant definition" errors.
  162.     
  163.     
  164.     INVOKING THE SMALL-MAC PROGRAMS
  165.     
  166. è    All of the Small-Mac programs produce listings and error diagnostics
  167.     on the standard output file.  So these  may  be  redirected  to  the
  168.     printer  by  giving  >LST:  in  the  command  line,  or  they may be
  169.     redirected to a file by giving >filename in the  command  line.    A
  170.     usage  message  may  be  invoked  by  executing and of the Small-Mac
  171.     
  172.     (7-10-85)                 Small-Mac User Notes                page 4
  173.  
  174.     Programs with just a hyphen (-) in the command  line  following  the
  175.     program name.
  176.     
  177.     
  178.                  ------ MAC: The Small-Mac Assembler ------
  179.     
  180.     usage: MAC [-L] [-NM] [-P] [object] source...
  181.     
  182.     -L         Generate an assembly listing on the standard output file.
  183.     
  184.     -NM        No macro processing.  This speeds up the assembler
  185.                somewhat.  Macro processing is NOT needed for Small-C 2.1
  186.                output files.
  187.     
  188.     -P         Pause on errors waiting for an operator response of CR.
  189.     
  190.     object     Name of the object file to be output.  It must have a REL
  191.                extension to be recognized as the output file.  A drive
  192.                specifier is allowed.  If not specified, the object code
  193.                will go into a file (on the default drive) bearing the
  194.                same name as the first source file, but with a REL
  195.                extension.
  196.     
  197.     source...  Names of the source files to be assembled.  The default,
  198.                and only allowed, extension is MAC.  A drive specifier is
  199.                allowed.  The named files will be assembled as one file
  200.                concatenated in the order given.
  201.     
  202.     The module name in the REL file will  be  taken  from  the  first  6
  203.     characters of the object filename.
  204.     
  205.     
  206.                 ------ LNK: Small-Mac Linkage Editor  ------
  207.     
  208.     usage: LNK [-B] [-G#] [-M] program [module/library...]
  209.     
  210.     -B                 A BIG program is being linked, so use all
  211.                        of free memory for the symbol table and load the
  212.                        program to disk entirely.  This is slower but it
  213.                        gets the job done.
  214.     
  215.     -G#                Make program absolute at address # (hex) and
  216.                        output as "program.LGO" instead of "program.COM".
  217.     
  218.     -M                 Monitor linking activity.
  219.     
  220.     program            A file specifier for the program being linked.
  221. è                       The efault, and only allowed, extension is REL.
  222.     
  223.     module/library...  A list of zero or more module (.REL) and/or
  224.                        library (.LIB) files.  Each module is linked to
  225.                        the program and the libraries are searched for
  226.                        just those modules which satisfy one or more
  227.                        unresolved external references.
  228.     
  229.     
  230.     (7-10-85)                Small-Mac User Notes                 page 5
  231.  
  232.     Merely  declaring  a symbol to be external will cause it's module to
  233.     be loaded.  It need not actually be referenced.
  234.     
  235.     The module  END  in  C.LIB  must be loaded last of all.  That module
  236.     contains special code which  identifies  the  physical  end  of  the
  237.     program and  the  beginning of free memory.  The linker is sensitive
  238.     to its name and waits until all  other  modules  are  loaded  before
  239.     loading END.
  240.     
  241.     The  absence  of  an  extension,  or  a .REL extension, identifies a
  242.     module; whereas,  a  LIB  extension  identifies  a  library.      If
  243.     necessary,  a  library  is  rescanned  to  resolve backward external
  244.     references between modules within the library.    Module  files  and
  245.     libraries  are  processed  in  the  order in which they occur in the
  246.     command line.
  247.     
  248.     Drive Designators (e.g.  B:):
  249.        - allowed with module and library names
  250.        - program drive designator locates the input .REL file
  251.        - output goes to the default drive
  252.     
  253.     Filename Extensions:
  254.        - must specify .LIB with library name
  255.        - standard extensions are:
  256.     
  257.        .REL = relocatable object module
  258.        .LIB = library of object modules
  259.        .NDX = index to library (not user specified)
  260.        .COM = CP/M command file (default output)
  261.        .LGO = load-and-go file (-G# output)
  262.        .O$ = temporary overflow file
  263.        .R$ = temporary reference file
  264.     
  265.     Enter control-S to pause and control-C to abort.
  266.     
  267.     NOTE: Compile only with Small-C 2.1 (edit level 63) or later.   Edit
  268.     63  fixes  CSYSLIB  so that when it overflows a buffer while writing
  269.     into a file it will no longer assume that it is at the  end  of  the
  270.     file.   This  prevents it from padding a sector with 1A (hex) in the
  271.     middle of a file when random access is being used.
  272.     
  273.     
  274.               ------ LGO: Small-Mac Load-and-Go Loader  ------
  275.     
  276. è    usage: LGO [-G] [-M] program
  277.     
  278.     -G     Execute program after loading.
  279.     
  280.     -M     Monitor load address and size.
  281.     
  282.     "Program"  is  a  file  specifier  for  the  program  being  loaded.
  283.     Default, and only allowed, extension is LGO.
  284.     
  285.  
  286.  
  287.     
  288.     (7-10-85)                 Small-Mac User Notes                page 6
  289.  
  290.     Enter control-S to pause and control-C to abort.
  291.     
  292.     
  293.         ----- LIB.C -- Small-Mac Relocatable-Library Manager  -----
  294.     
  295.     usage: LIB -{DPTUX}[A] library [module...]
  296.     
  297.     -D     delete named modules
  298.     -P[A]  print named, or all (-PA), modules on stdout
  299.     -T[A]  table of contents of named, or all (-TA), files on stdout
  300.     -U     update (adding/replace) named modules
  301.            (gets module names from stdin if not in command line)
  302.     -X[A]  extract named, or all (-XA), modules
  303.     
  304.     The A suffix obviates prompting stdin for module names when none are
  305.     in the command  line.    This  is  handy  for  eliminating  operator
  306.     intervention especially  in  batch mode.  Ordinarily when no modules
  307.     are given in the command line, LIB prompts the user (if stdin is not
  308.     redirected) and accepts one module name at a time from  stdin.    If
  309.     none  are given (CR response to first prompt) and the command switch
  310.     is -P, -T, or -X then all members of the library are processed.
  311.     
  312.     Drive Designators (e.g.  B:):
  313.        - allowed with any library and module names
  314.        - new library and index go on same drive as old
  315.        - will default to the default drive
  316.     
  317.     Filename Extensions:
  318.        - do NOT specify with library or module names
  319.        - standard extensions are:
  320.     
  321.        .REL = relocatable object module
  322.        .LIB = library of object modules
  323.        .NDX = index to library
  324.        .L$ = temporary new library
  325.        .N$ = temporary new index
  326.     
  327.     Enter control-S to pause and control-C to abort.
  328.     
  329.     
  330.            ------ CMIT: Compile Machine Instruction Table  ------
  331. è    
  332.     usage: CMIT [-C] [-L] [table] [mac] 
  333.     
  334.     -C     Configure the executable assembler (MAC.COM) with the
  335.            indicated, or default, machine instructin table.
  336.     
  337.     -L     List the compiled machine instruction table.
  338.     
  339.     table  The name of the machine instruction table file in source
  340.            format (default 8080.MIT).  The default and only allowed
  341.            filename extension is MIT.  A drive specifier is allowed.
  342.     
  343.  
  344.  
  345.     
  346.     (7-10-85)                Small-Mac User Notes                 page 7
  347.  
  348.     mac    Assembler COM file (default MAC.COM).  Must have COM extension
  349.            to be recognized as such.  Need specify only if not on the
  350.            default drive or has a different name.
  351.     
  352.     
  353.     If no switches are given, -L is assumed.  If any switches are given,
  354.     only those actions so specified are taken.
  355.     
  356.     After  compiling and linking a new MAC.COM, it must be configured by
  357.     running this program before  it  may  be  executed.    A  previously
  358.     configured MAC.COM may be reconfigured at any time.
  359.     
  360.     
  361.                  ------ DREL: Dump REL or LIB file  ------
  362.     
  363.     No command  line  switches  are  accepted.  The user is prompted for
  364.     each file to be dumped.  Output goes to the standard output file and
  365.     is, therefore, redirectable to any output device or to a disk  file.
  366.     If  an  input  file cannot be found the user is prompted for another
  367.     input file.  File names must be  given,  complete  with  extensions.
  368.     Drive specifiers may be given.
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386. è
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.     
  404.