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