home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 13 / AACD13.ISO / AACD / Programming / cfasm / Documentation / cfasm.txt < prev   
Encoding:
Text File  |  2000-08-20  |  12.0 KB  |  331 lines
  1.  
  2. Cfasm ColdFire Assembler (preliminary)
  3. rev. 1.09
  4.  
  5.  
  6. 1. GENERAL
  7.  
  8. The ColdFire Assembler, cfasm, is a freeware assembler for ColdFire processors. 
  9. Instruction set supported: 52xx, 5307 and 5407.
  10.  
  11. Command line arguments specify the filenames to assemble.  Only one object file is 
  12. output even though several files can be specified and assembled together. The 
  13. assembler can output in Motorola SREC, raw binary or GeckoOS object code 
  14. formats.
  15.  
  16. The object file is placed in the file `<inputfilename>.o' where 'inputfilename' was the 
  17. name of the actual assembler file (missing any extensions). The listing and error 
  18. messages are written to the standard output.
  19.  
  20. The listing file contains the address and bytes assembled for each line of input 
  21. followed by the original input line (unchanged, but moved over to the right some).  If 
  22. an input line causes more than 6 bytes to be output (e.g. a long dc.b directive), 
  23. additional bytes are listed on succeeding lines with no address preceding them.
  24.  
  25. Equates cause the value of the expression to replace the address field in the listing.  
  26. Equates that have forward references cause phasing Errors in Pass 2.
  27.  
  28. It is unwise to have more than one assembly in progress per directory since the 
  29. object file would be the same for all assemblies running.
  30.  
  31. 1.1 EXPRESSIONS
  32.  
  33. Expressions may consist of symbols, constants or the character '*' (denoting the 
  34. current value of the program counter) joined together by one of the operators: 
  35. +-*/%&|^<<>>~. 
  36.  
  37.         +    add
  38.         -       subtract
  39.         *       multiply
  40.         /       divide
  41.         %       modulo (remainder after division)
  42.         &       bitwise and
  43.         |       bitwise or
  44.         ^       bitwise exclusive-or
  45.         <<    bitwise left shift
  46.         >>    bitwise right shift
  47.         ~    ones complement
  48.  
  49. Expressions are evaluated left to right and there is no provision for parenthesized 
  50. expressions.  Arithmetic is carried out in signed 32-bit twos-complement integer 
  51. precision.
  52.  
  53.  
  54.  
  55. 1.2 CONSTANTS
  56.  
  57. Constants are constructed as follows:
  58.  
  59.         0x    followed by hexadecimal constant
  60.         $       followed by hexadecimal constant
  61.         @       followed by octal constant
  62.         %       followed by binary constant
  63.         digit     decimal constant
  64.  
  65. String constants are specified by enclosing the string in single quotes.  Strings are 
  66. only recognized by the DC pseudo-op.
  67.  
  68. 1.3 ERRORS
  69.  
  70. Error diagnostics are placed in the listing file just before the line containing the error.  
  71. Format of the error line is:
  72.  
  73.         Line_number: Description of error
  74.             or
  75.         Line_number: Warning --- Description of error
  76.  
  77. Errors of the first type in pass one cause cancellation of pass two.  Warnings do not 
  78. cause cancellation of pass two but should cause you to wonder where they came 
  79. from.
  80.  
  81. Error messages are meant to be self-explanatory. If more than one file is being 
  82. assembled, the file name precedes the error:
  83.  
  84.         File_name,Line_number: Description of error
  85.  
  86. Finally, some errors are classed as fatal and cause an immediate termination of the 
  87. assembly.  Generally these errors occur when a temporary file cannot be created or 
  88. is lost during the assembly.
  89.         
  90. The exit status of the assembler ($status for csh users) is equal to the number of 
  91. errors detected during the assembly.
  92.  
  93. 1.4 PSEUDO OPS
  94.  
  95.     The pseudo-ops (pseudo operations) are:
  96.         org        Origin (checks for word alignment)
  97.         equ        Equates
  98.         dc                 Define constant(s)
  99.         dr        Define relative(s) (usually used for library offset tables)
  100.         ds              Define storage
  101.         opt        Options
  102.         section        set to either code, data or bss
  103.         xref  <symbol>    external symbol reference. The symbol exists in another file.
  104.         xdef  <symbol>    external symbol definition. This symbol can be referenced from another file.
  105.         idnt <name>,<version>,<date>  Identification strings. Each string will cause the generation of
  106.                 individual GeckoOS blocks of type BLOCK_NAME, BLOCK_VERSION and
  107.                 BLOCK_DATE (only if object code option enabled).
  108.         include <file>          Filename of include file to be processed.
  109.         incdir        Include directory. Include files are first searched in the
  110.                 current directory and then in the incdir directory.
  111.         incbin <file>    Include a binary file into the assembly. This file is not assembled, but added 
  112.                 as if it were raw data. Useful for tables, graphic images etc...
  113.         lvorst        Reset library vector offset counter.
  114.         lvo <symbol>    Library vector offset entry.
  115.         call <symbol>    Call a library function using lvo, register A6 points to library base
  116.         push {reglist}  Performs;
  117.                   lea.l -x(a7),a7
  118.                   movem.l {reglist},(a7)
  119.                 where x is the number of registers*4
  120.         pull {reglist}  Performs;
  121.                   movem.l (a7),{reglist}
  122.                   lea.l x(a7),a7
  123.                 where x is the number of registers*4
  124.  
  125.         structure <symbol>,<value>  Creates a new symbol set to value. An internal
  126.                 variable is also set to the value.
  127.         stkstruct <symbol>,<value>  Creates a new symbol set to value. An internal
  128.                 variable is also set to the value. The stack structure
  129.                 defines all further components to negative values.
  130.         struct <symbol>,<value>  Creates a new symbol set to current internal value and
  131.                 the value is then added to the internal.
  132.         byte <symbol>   Creates a new symbol set to current internal value and increments
  133.                 the internal value by one except if defined as a stack structure
  134.                 in which case the internal value is decremented first by one and
  135.                 then set to the symbol.
  136.         word <symbol>   Creates a new symbol set to current internal value and increments
  137.                 the internal value by two except if defined as a stack structure
  138.                 in which case the internal value is decremented first by two and
  139.                 then set to the symbol.
  140.         long <symbol>   Creates a new symbol set to current internal value and increments
  141.                 the internal value by four except if defined as a stack structure
  142.                 in which case the internal value is decremented first by four and
  143.                 then set to the symbol.
  144.         label <symbol>    The symbol is set to the current internal value.
  145.  
  146.         aptr <symbol>    Absolute pointer, same as long.
  147.         rptr <symbol>    Relative pointer, same as long.
  148.         ulong <symbol>    Unsigned long, same as long.
  149.         fixed <symbol>    Fixed point value, same as long.
  150.         float <symbol>    Floating point value, same as long.
  151.  
  152.         short <symbol>    Short integer, same as word.
  153.         ushort <symbol>    Unsigned short, same as word.
  154.         uword <symbol>    Unsigned word, same as word.
  155.         
  156.         char <symbol>    Character, same as byte.
  157.         ubyte <symbol>    Unsigned byte, same as byte.
  158.  
  159.         bitdef <prefix>,<symbol>,<bitnum>
  160.                 Creates two symbols based on the prefix. The first symbol is a
  161.                 bit version and the second is a mask version. e.g. 
  162.                 
  163.                   bitdef PA,STATUS,2
  164.                 
  165.                 produces PAB_STATUS with the value 2 and PAF_STATUS with the value
  166.                 1<<2 or 4.
  167.  
  168.                   bitdef PRE,DATA,7
  169.                 
  170.                 produces PREB_DATA with the value 7 and PREF_DATA with the value
  171.                 1<<7 or 128.
  172.  
  173.  
  174.     1.4.1 CONDITIONAL
  175.         
  176.         endc        Terminate a conditional assembly block.
  177.         else        Assemble code based on previous condition statement.
  178.         ifd <symbol>    If symbol defined, then assemble the next block of code until
  179.                 an 'endc' pseudo-op.
  180.         ifnd <symbol>    If symbol not defined, then assemble the next block of code until
  181.                 an 'endc' pseudo-op.
  182.         ifeq <expr>    If expression evalutes to zero, then assemble next code block.
  183.         ifne <expr>    If expression evalutes to non-zero, then assemble next code block.
  184.         ifge <expr>    If expression evalutes to >=0, then assemble next code block.
  185.         ifgt <expr>    If expression evalutes to >0, then assemble next code block.
  186.         ifle <expr>    If expression evalutes to <=0, then assemble next code block.
  187.         iflt <expr>    If expression evalutes to <0, then assemble next code block.
  188.  
  189.     1.4.2 OPT pseudo-op
  190.  
  191.         list        Turn on output listing
  192.         nolist      Turn off output listing (default)
  193.         brl         Force forward refs long (default is long)
  194.         object        Produce object code output (GeckoOS format)
  195.         binary        Produce binary output (overridden by object flag, raw format)
  196.         rtxnop        Adds NOP instruction after RTS or RTE instructions
  197.  
  198.     The above pseudo-ops are treated as mnemonics, and must be 
  199.     preceded by at least one white space character in the assembly
  200.     file.    
  201.  
  202.     Some of the more common pseudo-ops are not present:
  203.  
  204.         spc         Use blank lines instead
  205.         pag[e]      Use a comment with cntrl-L imbeded
  206.         end         The assembly ends when there is no more input
  207.         ttl         use `pr' to get headings and page numbers
  208.         nam[e]  
  209.  
  210.     The above pseudo-ops are recognized, but ignored.
  211.  
  212. 2. DETAILS
  213.  
  214.         Symbol:  A string of  characters  with  a  non-initial  digit.  The
  215.                 string of characters may be from the set:
  216.  
  217.                [a-z][A-Z]_[0-9]$
  218.  
  219.                 ( _ count as a non-digit).  The `$' counts as a digit to
  220.                 avoid confusion with hexadecimal constants.  All characters
  221.                 of a symbol are significant, with upper and lower case
  222.                 characters being distinct.  The maximum number of
  223.                 characters in a symbol is currently set at 30.
  224.  
  225.                 The symbol table can grow until the assembler runs out of
  226.                 memory.
  227.  
  228.         Label:  A symbol starting in the first column is a  label  and  may
  229.                 optionally  be  ended  with a ':'.  A label may appear on a
  230.                 line by itself and is then interpreted as:
  231.  
  232.             Label   EQU     *
  233.  
  234.         Local:      A local label is defined as any label ending in a '$'. This
  235.                 label is special in that it belongs only between two normal
  236.                 labels. e.g. 
  237.             
  238.                 Start:
  239.                     nop
  240.                 10$    bra    10$
  241.                 Mid:
  242.                     nop
  243.                 10$    bra    10$
  244.             EndCode:
  245.  
  246.         Mnemonic:  A symbol preceded by at least one white space  character.
  247.                 Upper  case characters in this field are converted to lower
  248.                 case before being checked as a legal mnemonic.  Thus `nop',
  249.                 `NOP' and even `NoP' are recognized as the same mnemonic.
  250.  
  251.         Operand:  Follows mnemonic, separated by at  least  one  white space
  252.                 character.   The   contents   of   the   operand  field  is
  253.                 interpreted by each instruction.
  254.  
  255.         White space: A blank or a tab
  256.  
  257.         Comment:  Any text after all operands for  a  given  mnemonic  have
  258.                 been  processed or, a line beginning with '*' or '#' up to the 
  259.          end of line or, an empty line.
  260.  
  261.         Continuations:  If a line ends with a backslash (\) then  the  next
  262.                 line  is  fetched  and  added to the end of the first line.
  263.                 This continues until a line is seen which doesn't end in  \
  264.                 or  until  MAXBUF characters have been collected (MAXBUF >=
  265.                 256 ).
  266.  
  267. 2.1 BRANCHES
  268.  
  269.     Branches can contain byte,word or long (V4 only) offsets. Word offset is the
  270.     default for unspecified branches. E.g.;
  271.     
  272.     bra    10$    ; Defaults to word offset
  273.     bra.b    10$    ; Byte offset
  274.     bra.w    10$    ; Word offset
  275.     bra.l    10$    ; Longword offset (V4 Core only)
  276.  
  277.     Some branch optimising is implemented for backward branches, so that a 
  278.     word offset could be reduced to a byte offset if possible.
  279.     
  280. 3. COMMAND LINE OPTIONS
  281.  
  282.     -b        Produce binary output
  283.     -d        Turn off '.' local labels (use with cfcc)
  284.     -f        Forward branches default to byte offset
  285.     -l        Turn listing on
  286.     -o        Produce object code output
  287.     -r        Turn on RTS/RTE post NOP generation
  288.     -x <val>        Debug Options (see section 4)
  289.  
  290. 4. DEBUG OPTIONS    
  291.  
  292.     The debug option (-x) uses a weighted number to turn on
  293.     one or more print statements:
  294.  
  295.         1       Parser
  296.         2          Template matches
  297.         4       Expression Evaluation
  298.         8       Symbol table lookup/install
  299.                16      Forward references
  300.                32      Indexed Indirect information
  301.               64      Dump all important tables
  302.  
  303.     e.g. -x10 displays template match operation and symbol table info.
  304.  
  305. 5. FILES
  306.  
  307.     <infile>.o    object file output (SREC,OBJ or BIN)
  308.     STDOUT          listing and errors
  309.  
  310. 6. IMPLEMENTATION NOTES
  311.  
  312.         This is a classic 2-pass assembler.  Pass 1 establishes the  symbol
  313.         table and pass 2 generates the code.
  314.  
  315. 7. BUGS
  316.  
  317.     This assembler is still under development.
  318.  
  319.     1. If the last line of assembler is a comment, output code will not be
  320.         produced.
  321.  
  322.     2. The assembler may crash if compiling non-ascii files accidentally.
  323.  
  324.  
  325.     Original Code - Copyright (C) Motorola, used with permission.
  326.     Copyright (C) 1998-2000 Defiant Pty Ltd.
  327.     All rights reserved.
  328.  
  329.     www.defiant.com.au
  330.  
  331.