home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 6 / FreshFish_September1994.bin / new / dev / c / hce / docs / a68k.doc next >
Text File  |  1992-09-02  |  29KB  |  691 lines
  1.     A68k - a freely distributable assembler for the Amiga
  2.  
  3.             by Charlie Gibbs
  4.  
  5.              with special thanks to
  6.         Brian R. Anderson and Jeff Lydiatt
  7.  
  8.                 (Version 2.61 - January 11, 1990)
  9.  
  10.      Note:  This program is Freely Distributable, as opposed to Public
  11. Domain.  Permission is given to freely distribute this program provided no
  12. fee is charged, and this documentation file is included with the program.
  13.  
  14.      This assembler is based on Brian R. Anderson's 68000 cross-
  15. assembler published in Dr. Dobb's Journal, April through June 1986.
  16. I have converted it to produce AmigaDOS-format object modules, and
  17. have made many enhancements, such as macros and INCLUDE files.
  18.  
  19.      My first step was to convert the original Modula-2 code into C.
  20. I did this for two reasons.  First, I had access to a C compiler, but
  21. not a Modula-2 compiler.  Second, I like C better anyway.
  22.  
  23.      The executable code generator code (GetObjectCode and MergeModes)
  24. is essentially the same as in the original article, aside from its
  25. translation into C.  I have almost completely rewritten the remainder
  26. of the code, however, in order to remove restrictions, add enhancements,
  27. and adapt it to the AmigaDOS environment.  Since the only reference book
  28. available to me was the AmigaDOS Developer's Manual (Bantam, February
  29. 1986), this document describes the assembler in terms of that book.
  30.  
  31.  
  32. RESTRICTIONS
  33.  
  34.      Let's get these out of the way first:
  35.  
  36.       o The verification file (-v) option is not supported.  Diagnostic
  37.     messages always appear on the console.  They also appear in the
  38.     listing file, however (see extensions below).  You can produce
  39.     an error file by redirecting console output to a file - the
  40.     line number counter and final summary are displayed on stderr
  41.     so you can still see what's happening.
  42.  
  43.       o The file names in the INCLUDE directory list (-i) must be
  44.     separated by commas.  The list may not be enclosed in quotes.
  45.  
  46.       o Labels assigned by EQUR and REG directives are case-sensitive.
  47.  
  48.       o Strange things will happen if your source code (including
  49.     INCLUDE files and macro expansions) exceeds 32,766 lines.
  50.     Tough darts.  Break up your source file.  Can you actually
  51.     read that monster?  :-)
  52.  
  53.       o The following directives are not supported, and will be flagged
  54.     as invalid op-codes:
  55.  
  56.         OFFSET
  57.         NOPAGE
  58.         LLEN
  59.         PLEN
  60.         NOOBJ
  61.         FAIL
  62.         FORMAT
  63.         NOFORMAT
  64.         MASK2
  65.  
  66.     I feel that NOPAGE, LLEN, and PLEN should not be defined within
  67.     a source module.  It doesn't make sense to me to have to change
  68.     your program just because you want to print your listings on
  69.     different paper.  The command-line switch "-p" (see below) can
  70.     be used as a replacement for PLEN; setting it to a high value
  71.     (like 32767) is a good substitute for NOPAGE.  The effect of
  72.     LLEN can be obtained by running the listing file through an
  73.     appropriate filter.
  74.  
  75.  
  76. EXTENSIONS
  77.  
  78.      Now for the good stuff:
  79.  
  80.       o Labels can be any length that will fit onto one source line
  81.     (currently 127 characters maximum).  Since labels are stored
  82.     on the heap, the number of labels that can be processed is
  83.     limited only by available memory.
  84.  
  85.       o The first character of a label can be '@' if the next character
  86.     is not numeric (this avoids confusion with octal constants).
  87.     This provides compatibility with the Lattice C compiler.
  88.  
  89.       o Since section data and user macro definitions are stored in
  90.     the symbol table (see above), they too are limited only by
  91.     available memory.  (Actually, there is a hard-coded limit of
  92.     32,767 sections, but I doubt anyone will run into that one.)
  93.  
  94.       o The only values a label cannot take are the register names -
  95.     A68k can distinguish between the same name used as a label,
  96.     instruction name or directive, macro name, or section name.
  97.  
  98.       o Section and user macro names appear in the symbol table dump,
  99.     and will also be cross-referenced.  Their names can be the same
  100.     as any label (see above); they will be listed separately.
  101.  
  102.       o INCLUDEs and macro calls can be nested indefinitely, limited
  103.     only by available memory.  The message "Secondary heap
  104.     overflow - assembly terminated" will be displayed if memory
  105.     is exhausted.  You can increase the size of this heap using
  106.     the -w switch (see below).  Recursive macros are supported;
  107.     recursive INCLUDEs will, of course, result in a loop that
  108.     will be broken only when the heap overflows.
  109.  
  110.       o The EVEN directive forces alignment on a word (2-byte)
  111.     boundary.  It does the same thing as CNOP 0,2.
  112.     (This one is left over from the original code.)
  113.  
  114.       o Backward references to labels within the current CODE section
  115.     will be converted to PC-relative addressing with displacement
  116.     if this mode is legal for the instruction.  This feature is
  117.     disabled by the -n switch.
  118.  
  119.       o If a MOVEM instruction only specifies one register, it is
  120.     converted to the corresponding MOVE instruction.  Instructions
  121.     such as MOVEM D0-D0,label will not be converted, however.
  122.     This feature is disabled by the -n switch.
  123.  
  124.       o ADD, SUB, and MOVE instructions will be converted to ADDQ,
  125.     SUBQ, and MOVEQ respectively if possible.  Instructions coded
  126.     explicitly (e.g. ADDA or ADDI) will not be converted.  This
  127.     feature is disabled by the -n switch.
  128.  
  129.       o ADD, CMP, SUB, and MOVE to an address register are converted to
  130.     ADDA, CMPA, SUBA, and MOVEA respectively, unless (for ADD, SUB,
  131.     or MOVE) they have already been converted to quick form.
  132.  
  133.       o ADD, AND, CMP, EOR, OR, and SUB of an immediate value are
  134.     converted to ADDI, ANDI, CMPI, EORI, ORI, and SUBI respectively
  135.     (unless the address register or quick conversion above has
  136.     already been done).
  137.  
  138.       o If both operands of a CMP instruction are postincrement mode,
  139.     the instruction is converted to CMPM.
  140.  
  141.       o Operands of the form 0(An) will be treated as (An) except for
  142.     the MOVEP instruction, which always requires a displacement.
  143.     This feature is disabled by the -n switch.
  144.  
  145.       o The SECTION directive allows a third parameter.  This can be
  146.     specified as either CHIP or FAST (upper or lower case).  If
  147.     this parameter is present, the hunk will be written with the
  148.     MEMF_CHIP or MEMF_FAST bit set.  This allows you to produce
  149.     "pre-ATOMized" object modules.
  150.  
  151.       o The synonyms DATA and BSS are accepted for SECTION directives
  152.     starting data or BSS hunks.  The CHIP and FAST options (see
  153.     above) can also be used, e.g. BSS name,CHIP.
  154.  
  155.       o The following synonyms have been implemented for compatibility
  156.     with the Aztec assembler:
  157.         CSEG is treated the same as CODE or SECTION name,CODE
  158.         DSEG is treated the same as DATA or SECTION name,DATA
  159.         PUBLIC is treated as either XDEF or XREF, depending on
  160.             whether or not the symbol in question has been
  161.             defined in the current source module.
  162.             A single PUBLIC directive can name a mixture
  163.             internally- and externally-defined symbols.
  164.  
  165.       o The ability to produce Motorola S-records is retained from the
  166.     original code.  The -s switch causes the assembler to produce
  167.     S-format instead of AmigaDOS format.  Relocatable code cannot
  168.     be produced in this format.
  169.  
  170.       o Error messages consist of three parts.
  171.         The position of the offending line is given as a line
  172.     number within the current module.  If the line is within a
  173.     macro expansion or INCLUDE file, the position of the macro
  174.     call or INCLUDE statement in the outer module is given as
  175.     well.  This process is repeated until the outermost source
  176.     module is reached.
  177.         Next, the offending source line itself is listed.
  178.         Finally, the errors for that line are displayed.  A flag
  179.     (^) is placed under the column where the error was detected.
  180.  
  181.       o Named local labels are supported.  These work the same as the
  182.     local labels supported by the Metacomco assembler (nnn$) but
  183.     are formed in the same manner as normal labels, except that
  184.     they must be preceded by a backslash (\).
  185.  
  186.       o The following synonyms have been implemented for compatibility
  187.     with the Assempro assembler:
  188.         ENDIF is treated the same as ENDC
  189.         = is treated the same as EQU
  190.         | is treated the same as ! (logical OR)
  191.  
  192.       o Quotation marks (") can be used as string delimiters
  193.     as well as apostrophes (').  Any given string must begin
  194.     and end with the